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PREFACE 


MANUAL OBJECTIVES 


The VAX-1l1 Linker Reference Manual describes how the VAX-11_ Linker 


works and tells you how to use it. This manual is designed to educate 
as well as to provide easy reference. 


INTENDED AUDIENCE 


This manual is intended for programming specialists and nonspecialists 
alike. Certain parts of the manual are designed specifically to meet 
the needs of certain types of readers. 


e If you are not yet proficient in programming under the VAX/VMS 
system or if you do not need to become an expert, this manual 
is designed to teach you the main concepts and techniques of 
linking as clearly as_ possible, Chapters 1 through 6 and 
Appendixes A and B are aimed especially at this type of 
reader. 


e If you are already proficient in programming under the VAX/VMS 
system, this manual provides detailed information about some 
of the more complex aspects of linking. Chapters 7 and 8 and 
Appendixes C and D are aimed especially at this type of 
reader. 


STRUCTURE OF THIS DOCUMENT 


Chapter 1 introduces the linker. It defines significant terms, 
presents the reasons for the linker's existence, and discusses in 
general terms how the linker works. 


Chapters 2 and 3 focuS on concepts important to understanding the 
linker's operation. The discussion of symbols and references in 
Chapter 2 derives from the linker's function of resolving symbolic 
references between modules. Chapter 3 explains libraries, which 
normally contain frequently used modules that the linker can include 
in user images. 


Chapter 4 discusses the LINK command and its command and file 
qualifiers. Chapter 5 focuses on the /OPTIONS file qualifier, 
describing how to create and use a linker options file. 


Chapter 6 explains the various forms of the image map that the linker 


produces on request. This map provides information about the image 
that was created and about the linking process itself. 
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Chapter 7 goes more deeply into the process by which the linker 
creates images. Chapter 7 expands on concepts introduced in Chapter l 
and introduces new concepts. . 


Chapter 8 presents detailed explanations of shareable images. The 
complex information in this chapter is intended mainly for more 
sophisticated programmers and application designers. 


The appendixes provide supplementary information. Appendix A lists 
the error messages that the linker can _ generate. Appendix B 
illustrates complete brief, default, and full maps of the same image. 
Appendix C is a specification of the object language accepted by the 
linker; this information is useful to anyone designing a compiler or 
assembler whose output must be acceptable to the VAX-11 Linker. 
Appendix D explains the object module analysis (ANALYZE) program. 


ASSOCIATED DOCUMENTS 
The following documents contain information pertinent to linking: 


e VAX-11 Information Directory and Index 





@e VAX/VMS Primer 





e VAX/VMS System Manager's Guide 





e The user's guide for your programming language(s) 


This document uses the following conventions: 


Convention Meaning 
Uppercase words Uppercase words and letters, used in examples, 
and letters indicate that you should type the word or 
letter exactly as shown. 
Lowercase words Lowercase words and letters, used in format 
and letters examples, indicate that you are to substitute 


a word or value of your choice. 


Quotation marks The term quotation marks is used to refer to 
Apostrophes double quotation marks ("). The term 
apostrophe (') is used to refer to a single 


quotation mark. 


{[ ] Square brackets indicate that the enclosed 
item is optional (except when used in file 
specifications where square brackets delimit 
directory names). 


{ } Braces are used to enclose lists from which 
one element is to be chosen. 

piece A horizontal ellipsis indicates’ that the 
preceding item(s) can be repeated one or more 
times. 

. A vertical ellipsis indicates that not all of 

. the statements in an example or figure are 

zi shown. 


SUMMARY OF TECHNICAL CHANGES 


This manual describes the VAX-1l Linker, Version 2. The following are 
technical changes from the previous version. 


User-defined default object libraries are allowed. These libraries do 
not have to be explicitly specified in the LINK command and are 
searched before the system default libraries. The LINK command 
qualifier /USERLIBRARY controls user-defined default object libraries. 


When creating a shareable image, the linker defers the relocation of 
virtual addresses, Deferred relocation allows the linker to create 
position-independent shareable images that contain relocatable address 
data. Each user is given aeprivate copy of image sections that 
contain relocatable address data. 


The linker supports 3l-character symbol names. 


The linker can create three new kinds of images: 1) system images 
with image headers, 2) executable images that are only stored in PO 
address space, and 3) protected shareable images. The LINK command 
qualifiers /HEADER, /POIMAGE, and /PROTECT are used to create these 
images. The PROTECT= linker option and the VEC program section 
attribute can also be used to create protected shareable images. 


The order of image sections within a cluster and the order of clusters 
within an image section has been changed. 


The PSECT ATTR= linker option changes program section attributes when 
an image is being linked. The COLLECT= linker option collects program 
sections into specified clusters. 


The default values for the GSMATCH= option have changed. An 
executable image that is linked with a shareable image created with 
the default GSMATCH= option must be relinked if the shareable image is 
changed. 


The ANALYZE utility is provided to analyze the contents of object 


modules and to ensure that they conform to the object language 
specification. 
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CHAPTER 1 


LINKER OVERVIEW 


The VAX-11 Linker is a programming development tool that takes the 
output of a native mode language translator, such as an assembler or 
compiler, and binds it into a form that can be executed on the VAX-11 
hardware. The primary input to the VAX-11 Linker is the primary 
output from the VAX-11 language compilers and assembler: files that 
contain object modules. The primary output of the linker is a file 
called an image. 


The linker can produce three types of images. The most common type, 
called executable, is activated in response to a command that you 
enter (such as RUN). Another type of image, called system, is 
intended for stand~alone execution on the VAX~-11 hardware. The third 
type, called shareable, provides a means for sharing procedures and 
data among multiple processes within the system. You use a shareable 
image by running an executable image that has been linked with it. 
Shareable images also provide a way of linking a very large 
application program in a number of smaller phases. Chapter 7 
discusses image creation in detail. Chapter 8 focuses on shareable 
images. 


The linker assigns values and virtual addresses not only to_ symbols 
defined within each module, but also to symbols defined outside the 
module that refers to them. If a symbol is not defined in a module 
named in the LINK command, the linker searches one or more libraries 
to find the definition of the symbol. Chapter 2 discusses the various 
types of symbols. Chapter 3 discusses the use of libraries. 


The linker is activated by the LINK command, which you can enter 
interactively or within a command procedure. The LINK command permits 
many command and file qualifiers, most of which have default values 
that are suitable for most cases. One input file qualifier is 
/OPTIONS, which allows you to convey additional input file 
specifications and special instructions for the linker. Chapter 4 
explains the LINK command and all its qualifiers. Chapter 5 focuses 
on the /OPTIONS qualifier and the special items or options that can 
appear in an options file. 


The linker can produce, in addition to the image itself, a printable 
image map. You can control the level of detail provided in various 
parts of the map. Chapter 6 explains and illustrates the image map. 
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1.1 REASON FOR A LINKER 


The object modules that a VAX-11 language compiler or assembler 
creates are nonexecutable. You must link the object modules before 
you can run them, 


The VAX-11 language compilers and assembler require a linker for 
several reasons: 


e Linking simplifies modular programming. 


e The linker simplifies the job of each language compiler or 
assembler. 


e The VAX-11 Symbolic Debugger and other features can be 
accessed easily. 


1.1.1 Modular Programming 


Modular programming is the process of combining separately compiled or 
assembled modules into an executable program or image. Modular 
programming has two aspects: 


@e Automatic modularity because different source language 
Statements generate calls to the same routine developed by 
DIGITAL (such as a routine to open or close a file) 


e Modular programming that you design into your program 


Some routines developed by DIGITAL that perform commonly needed 
functions are the procedures in the VAX-11 Common Run-Time Procedure 
Library, which is installed in the system as a shareable image. These 
routines can be linked into different images regardless of the 
program's original source language. At run time each routine can be 
shared by a number of different processes because each routine is 
relocatable and reentrant. (Reentrant code does not modify itself and 
consequently can be reused by different processes, ) 


Users can also make their programs deliberately modular. Under this 
practice, a single complex program is written as a number of smaller 
program modules. The modules are compiled or assembled separately and 
later linked to create an executable image. Figure 1-1 illustrates 
program development in this environment. In this example, two 
programmers write two program modules: a main section in VAX-11 
FORTRAN to perform various calculations, and a second section in 
VAX-11 MACRO to handle specific exception conditions. 


Modular programming offers several advantages over the traditional 
practice of having one programmer write an entire complex program as a 
single source module: 


e Smaller modules are usually more manageable and easier to 
write. 


e Different modules of the same program can be written in 
different languages. You can select the language that best 
suits the nature of the module's function or your own personal 
preference, 


e Errors are easier to analyze and correct in smaller modules. 
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FORTRAN 
Compiler 


MACRO 
Assembler 


Optional 


Figure 1-1 Modular Programming 


1.1.2 Simplifying Compilation And Assembly 


Having a linker perform certain essential functions eliminates the 
need for every native compiler and assembler to handle these 
functions. For example, the linker is able to allocate virtual memory 
and to provide the memory management interface between the program and 
the operating system. 


A program's virtual memory can be allocated efficiently only after all 
its constituent modules are _ known. The linker contains the logic 
necessary to group parts of programs according to specific attributes, 
with the goal of conserving memory and reducing the amount of paging 
activity at run time. 


Most programs interact with the operating system. For example, a 
program may use VAX/VMS system services. The linker can generate the 
proper program-to-system interfaces that are required. 


1.1.3 Debug Capability 


Use of the VAX-11 Linker allows you to access the VAX-11 Symbolic 
Debugger from the executable image. If you request the debugger, you 
can choose whether to activate it at run time. The VAX-11 Symbolic 


Debugger Reference Manual explains the capabilities and use of the 
debugger. Programmers should also refer to the information on 


debugging in their language user's guides. 
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1.2 LINKER OPERATION AND FUNCTIONS 
The linker performs the following operations when it creates an image: 
e Allocates virtual memory for the image 
e Resolves symbolic references among modules 
@ Initializes the image contents 
e Generates the image map, if requested 


@ Generates a symbol table file, if requested 


1.2.1 Virtual Memory Allocation 


The language translators that produce object modules do not allocate 
addresses for two reasons: 


e They do not know how the modules and sections of modules will 
be grouped in the final executable image. 


e They do not know how much address space is required for many 
of the external modules that are called by the module being 
assembled or compiled. 


The linker, then, must assume the task of allocating virtual memory 
for the image. Each object file input to the linker consists of one 
or more program Sections. The linker groups program sections from 
different object files according to various section attributes--for 
example, whether the program section is concatenated or overlaid and 
what its memory protection requirements are. For further information 
on how the linker maps the image, see Chapter 7. 


1.2.2 Resolution Of Symbolic References 


When a module makes references to symbols outside itself, the linker 
searches for these references in other modules explicitly named in the 
LINK command. If you specify any libraries, the linker searches’ them 
to resolve references made by preceding files named in the LINK 
command. If any references still remain unresolved, the linker 
searches any user-defined default libraries and the default system 
library. For a detailed discussion of libraries, see Chapter 3. 


1.2.3 Image Initialization 


After it maps virtual memory and resolves references, the linker fills 
in the actual contents of the image. This image initialization 
consists mainly of copying the binary data and code that was written 
by the compiler or assembler. However, the linker must perform two 
additional functions to initialize the image contents: 


e It must insert addresses into instructions that refer to 
externally defined fields. For example, if a module contains 
an instruction moving FIELDA to FIELDB, and if FIELDB is 
defined in another module, the linker must determine the 
virtual address of FIELDB and insert it into the instruction. 
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e It must compute values that depend on externally defined 
fields. For example, if a module initializes location X to 
contain Y plus Z, and if Y and Z are defined in an _ external 
module, the linker must compute the value of Y plus Z and 
insert it in xX. 


1.2.4 Image Map 


If you so 
contents 

you enter 
qualifier 


request, the linker generates an image map. The actual 
of the map depend on the map-related command qualifiers that 
with the LINK command; however, entering just the /MAP 
generates a default map with the following sections: 


e An object module synopsis 


e 6A 


eUA 


program section synopsis 


list of symbols, with the name and value of each 


e An image synopsis 


e Statistics of the link run 


Chapter 6 discusses the command qualifiers that affect the image map. 
It also illustrates the map sections and explains significant items. 


1.2.5 Symbol Table File 


T£ you so 


request, the linker produces a file that records the values 


of symbols defined within the image. Section 2.3.1 contains further 
information on the symbol table file. 
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SYMBOLS AND REFERENCES 


One of the linker's functions is to resolve symbolic references 
between modules. The linker recognizes different types of symbols and 
follows guidelines for each type when it tries to supply addresses or 
values to statements that refer to these symbols. 


2.1 DEFINITIONS: "SYMBOL" AND “REFERENCE” 


A symbol is a name associated with a coding statement or with a data 
area or field. A reference is the use of a symbol in a program 
statement or a data definition. Consider the following examples (not 
tied to a specific programming language): 


e A program statement identified as ROUTINEA moves FIELDA to 
FIELDB. ROUTINEA is’ the symbol associated with the program 
statement. FIELDA and FIELDB are references made by the 
statement. 


e A data definition statement defines FIELDA as being equal _ to 
(A+B) /2. FIELDA is the symbol associated with the computed 
value of (A+B)/2. A and B are references. 


2.2 TYPES OF SYMBOLS AND REFERENCES 
Each symbol is local, global, or universal: 


e Local symbols are available for reference only within the 
program module that defines them. 


e Global symbols can be referred to by modules outside the 
module that defines them. A global symbol has a strong or a 
weak definition (see Section 2.2.2). Another module can make 
a strong or a weak reference to a global symbol (regardless of 
whether the symbol's definition is weak or _ strong). The 
linker resolves the global references with the global 
definition in the other module. 


e Universal symbols are a special type of global symbol that can 
be specified only for shareable images. 
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Figure 2-1 illustrates references to local and global symbols in three 
modules, (The statements do not reflect a specific programming 
language.) An arrow is drawn between each reference and the symbol to 
which it refers. 


MODULEA 

















Move LOCAL1 to LOCAL2 
Call GLOBAL3 


MODULEB MODULEC 


LOCAL1 

LOCAL2 

Subtract GLOBAL2 
from LOCAL2 


ined 
GLOBAL3 
Move LOCAL2 
to LOCAL1 







Add GLOBAL1 
to LOCAL1 





Move LOCAL1 
to LOCAL2 






Figure 2-1 Local and Global Symbols 


Local and global symbols can be designated either automatically by the 
language compiler or explicitly by qualifiers in program statements. 
You can specify the local or global symbol type only in certain 
languages. In VAX-11 MACRO, for example, you can define a symbol as 
local or global by using one or two equal signs or colons, as_ the 
following statements show. Note that the term "local symbol" in this 
context is different from the term "local label" (for example, 10$:) 
in the context of a MACRO program. 


Statement Effect 


CRFC_MAXREC=292 Assigns a value of 292 to the local symbol 
CRFC_MAXREC 


CRFC_MAXREC==292 Assigns a value of 292 to the global symbol 
CRFC_MAXREC 


ERR_BRANCH: Makes the coding statement label ERR_BRANCH a 
local symbol 


ERR_BRANCH: : Makes the coding statement label ERR_BRANCH a 
global symbol 


In certain other languages, the compiler determines whether a_ symbol 
is local or global. For example, the FORTRAN compiler makes statement 
numbers local symbols, and it makes module entry points and common 
area names global symbols. For information about designating symbol 
type in a specific programming language, see the appropriate language 
reference manual. 
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Universal symbols must be specified by the UNIVERSAL= option in the 
linker options file. Chapter 5 explains the use of the /OPTIONS 
qualifier with the LINK command. 


2.2.1 Local Symbols 


You can refer to local symbols only within the object module that 
defines them. Most symbols in a typical program are local. 


The compiler or assembler resolves references to local symbols, and 
therefore they are not passed on to the linker. 


2.2.2 Global Symbols 


Global symbols can be referred to by object modules other than the 
module that defines them. 


Each global symbol has either a strong or a weak definition. An 
external module can make a strong reference or a weak reference to any 
global symbol. 


2.2.2.1 Strong Definition - A global symbol with a strong definition 
is available for reference if the module that defines it is either 
explicitly named in the LINK command or contained in a library that is 
searched by the linker. Global symbols usually have aé_=e strong 
definition, and strong is the default if neither weak nor strong is 
specified. 


The librarian utility makes an entry for each global symbol with a 
Strong definition in the global symbol table of a library. Libraries 
are discussed in Chapter 3. 


2.2.2.2 Weak Definition - A global symbol with a weak definition is 
available for reference only if the module that defines. it is 
explicitly included in the linking operation; that is, the module is 
listed as an input file, specified with the INCLUDE qualifier, or 
included from a library because another (strong) symbol in the module 
is needed. Weak symbols can be defined in VAX-11 MACRO and VAX-11 
BLISS. See the VAX-1l1 MACRO Language Reference Manual for more 
information. ° 


The librarian utility routine does not make entries for global symbols 
with weak definitions in the global symbol table of a library. 


2.2.2.3 Strong Reference - A strong reference is one ‘whose resolution 
is critical to the linking operation. If the linker cannot resolve 
all strong references by searching named input modules and libraries 
and the default system library, it reports errors and assumes that the 
symbol referred to has a value of zero. 


Most references to global symbols are strong, and strong is’ the 
default. 
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2.2.2.4 Weak Reference - A weak reference is one whose resolution is 
not critical to the linking operation. For a weak reference, the 
linker searches only named input modules, but not user libraries or 
the default system library. The linker does not treat an unresolved 
weak reference as an error, but it does assume that the symbol 
referred to has a value of zero. Weak references can be made in 
VAX~-11 MACRO, 


An example of the use of weak references might occur in a program that 
you want to Ilink now, but that you want to add to and relink later. 
In a particular subroutine you might make a weak reference to a symbol 
in an external module that will not be written until later. You can 
link the image and run it, as long as it does not try to use the 
nonexistent symbol during the run. 


2.2.3 Universal Symbols 


A universal symbol is a special type of global symbol in a _ shareable 
image. A universal symbol is accessible by other modules when they 
link with the shareable image. Universal symbols in a shareable image 
contrast with ordinary global symbols in the modules that make up the 
shareable image; the ordinary global symbols are available only when 
the modules are being linked to create the shareable image. 


VAX-11 MACRO provides the .TRANSFER directive to identify an important 
class of universal symbols, namely transfer vectors. Otherwise, you 
must identify universal symbols with the UNIVERSAL= option in a linker 
options file (see Chapter 5). For example, the following LINK command 
shows how to designate A and B as universal symbols in the _ shareable 
image ABBOTT. COSTELLO is an options file that includes the record 
UNIVERSAL=A,B. 


$ LINK/SHAREABLE ABBOTT ,COSTELLO/OPTIONS 


COSTELLO.OPT 


UNIVERSAL=A,B 





An example of the need for universal symbols might occur if you write 
an error-handling routine with several modules’ to be linked as a 
shareable image. You define global symbols for references between the 
modules. However, you must designate as universal any global symbols 
that are to be available when an executable image is linked with the 
shareable image. For example, the executable image needs access to 
the error-handling shareable image's entry points and perhaps’ some 
constants for defining possible errors. 


2.3 SYMBOL TABLES 


An image can have neither, one, or both of the following symbol 
tables: 


e A debug symbol table 


e A global symbol table 
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The debug symbol table is included only if you specify /DEBUG at link 
time. This debug symbol table normally contains the following types 
of information: 


e Module names 
e Routine names and/or program section names 
e All local symbols 


However, the local symbols are included only if you request debug at 
both compilation time and link time. 


The global symbol table is included in an executable image whenever 
you include debug in the link. The global symbol table is always 
included in a shareable image, regardless of the qualifiers you 
specify at link time. The global symbol table contains an entry for 
each global symbol in an executable image and for each universal 
symbol ina shareable image. These symbols are listed in the Symbols 
by Name section of the image map. 


2.3.1 Global Symbol Table As Separate Output 


You can output a copy of the image's global symbol table as a separate 
file by using the /SYMBOL TABLE qualifier at link time. The symbol 
table file is a sequential file containing variable-length records. 
Its format is identical to that of object modules (Appendix C explains 
this format in detail). 


You can specify a symbol table file as input to a linking operation. 
The linker makes the global symbols in the symbol table file and their 
values available to the object modules being linked, without also 
linking the entire image with which the global symbols are associated. 
One primary use for specifying symbol table files at link time is to 
make global symbols in a system image available to a number of other 
images without binding the system image into each of the other images. 
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LIBRARIES 


A library contains object modules and related information, including a 
list of the names of the modules and a list of the global symbols 
contained in the modules. (A library can contain modules other’ than 
object modules; however, the linker is only concerned with object 
libraries.) The linker searches one or more libraries to resolve 
references to global symbols that are not defined in the object files 
previously specified in the LINK command. 


When the linker matches a global symbol having an unresolved = strong 
reference with an entry ina library's table of global symbols, it 
binds the module that defines the symbol into the image. You can 
eliminate the need for the linker to search the global symbol table of 
the library by explicitly including modules from a library in an 
image. In addition to any libraries that you specify, the linker 
automatically searches the following for any unresolved strong 
references: 


e User-defined default libraries, if there are any (See Section 
3.3) 


e The default system library 


To create a library, you must use the LIBRARY command, which is 
explained in the VAX/VMS Command Language User's Guide. 


3.1 LIBRARY TABLES USED BY THE LINKER 


Each object module library contains two lists or tables that’ the 
linker uses to resolve symbolic references: 


@e A module name table, containing an entry for each object 
module in the library. Each entry includes the name of the 
module and its location within the library file. 


@ A global symbol table, containing an entry for each global 
symbol in the modules in the library. Each entry includes the 
name of the symbol and the location of the module that defines 
the symbol. 


For example, in a hypothetical library named MINE2, one of the modules 
is MODULEZ, which contains the global symbols TAG] and TAG2. Although 
it is not intended as an exact schematic illustration, Figure 3-1 
shows the relationship of the module name table and the global symbol 
table to the rest of the library. 
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Figure 3-1 Library Tables 
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3.2 LINKER’S USE OF LIBRARIES 


You can include library modules in the image either implicitly or 
explicitly: 


e Implicit inclusion occurs when a module specified in the LINK 
command refers to a global symbol defined in a library that 
the linker searches. For example, an instruction in a module 
named MODULE] moves FIELDA to FIELDB, yet FIELDB is defined 
only in the module LIBMOD3 in the library BOBLIB.OLB. You can 
specify: 


$ LINK MODULE1,BOBLIB/LIBRARY 


This causes the linker to search BOBLIB for any unresolved 
references from MODULE1. When it discovers that FIELDB is 
defined in LIBMOD3, the linker includes that module in the 
image. 


e Explicit inclusion occurs when you name a module with the 
INCLUDE qualifier after the library name. To use the example 
in the explanation of implicit inclusion, if you know that 
FIELDB is defined in module LIBMOD3 in BOBLIB, you can 
simplify the linker's search and explicitly include LIBMOD3 in 
the final executable image by specifying: 


$ LINK MODULE1,BOBLIB/INCLUDE=LIBMOD3 
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The linker follows these conventions in using libraries: 


e It processes all input files, including libraries, in the 
sequence in which you name them. Thus, the linker searches a 
library for unresolved strong references only from previously 
named input files. For example, assume that you enter the 
following command: 


$ LINK A,B,C/LIBRARY,D,E 


The linker searches library C for unresolved strong references 
from object modules A and B, but not D and E. The search of 
library C continues until no more symbols can be resolved. 
For example, if module X is included from library C and module 
X also has some unresolved strong references, the linker makes 
another search of library C. 


e If you specify both the /LIBRARY and /INCLUDE qualifiers after 
a library's file specification, the linker includes the named 
modules first and then, if necessary, searches the library. 
This is true regardless of the order of the two qualifiers. 
For example, the following two commands cause the linker to 
perform identical actions: 


$ LINK A,B/INCLUDE=(MOD1,MOD2) /LIBRARY 
$ LINK A,B/LIBRARY/INCLUDE=(MOD1,MOD2) 


e The linker searches the following default libraries for 
unresolved strong references after it has processed all named 
input files, including user libraries: 


~ Any user-defined default libraries (see Section 3.3) 
- The default system library (see Section 3.4) 


These conventions allow you considerable choice when the same global 
symbol name is defined differently in modules in different libraries. 
For example, if you know that a particular symbol is defined as you 
need it ina particular module but is defined differently in another 
module (in one of your libraries or the default system library), you 
can choose the desired definition by specifying the module with the 
INCLUDE qualifier. If you know that your own library has_ global 
symbols that are defined differently in the default system library, 
you can include your own symbols by specifying your library with the 
/LIBRARY qualifier. 


3.3 USER-DEFINED DEFAULT LIBRARIES 


You can define one or more default libraries for the linker to search 
before it searches the default system library. You must equate the 
logical names LNKSLIBRARY, LNKS$LIBRARY_1, and so on (up to 
LNK$LIBRARY_999) to the file specifications of your default libraries, 
You can define these logical names in the process, group, and system 
logical name tables. 


The linker automatically searches any user-defined default libraries 
for unresolved strong references, unless you specify the 
/NOUSERLIBRARY qualifier in the LINK command. You can specify in the 
/USERLIBRARY qualifier the tables, PROCESS, GROUP, or SYSTEM, that you 
want the linker to search. If you specify /USERLIBRARY without a 
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table list (or do not specify it at all), the linker assumes all 
tables are to be searched (/USERLIBRARY=ALL). The search of 
user-defined default libraries proceeds as follows: 


l. If you specify /USERLIBRARY=PROCESS or /USERLIBRARY, the 
linker searches the process logical name table for the name 
LNKSLIBRARY. If this entry exists, the linker translates the 
logical name and searches the specified library for 
unresolved strong references. If you exclude PROCESS from 
the table Ilsit in /USERLIBRARY or if no entry exists for 
LNKSLIBRARY, the linker proceeds to step 4 (searching the 
group logical name table). 


2. If any unresolved strong references remain, the linker 
searches the process logical name table for the name 
LNKSLIBRARY_1, and follows the logic of step 1. If no entry 
exists for LNKSLIBRARY 1, the linker proceeds to step 4 
(searching the group logical name table). 


3. If any unreSolved strong references remain, the linker 
follows the logic of step 1 for LNKS$LIBRARY 2, LNKS$LIBRARY_ 3, 
and so on, until it finds no match in the process’ logical 
name table, at which point it proceeds to step 4. 


4, If you specify /USERLIBRARY=GROUP or /USERLIBRARY, the linker 
follows the logic in steps 1-3 using the group logical name 
table. If you exclude GROUP from the table list in 
/USERLIBRARY or when any logical name translation fails, the 
linker proceeds to step 5. 


5. If you specify /USERLIBRARY=SYSTEM or /USERLIBRARY, the 
linker follows the logic in steps 1-3 using the system 
logical name table. If you exclude SYSTEM from the table 
list in /USERLIBRARY or when any logical name translation 
fails, the linker searches the default system library (if any 
unresolved strong references remain). 


An example use of user-defined default libraries is that you may want 
the linker to use your private libraries MINE1.0OLB and MINE2.0OLB as 
default libraries, and everyone in your group may want the linker’ to 
use [PROJX]PROJECTX.OLB as a default library. Moreover, the system 
manager may want SYSSLIBRARY:MYSITE.OLB as a default library for all 
users. The following commands make the necessary logical name 
definitions (the GRPNAM and SYSNAM privileges are required to use the 
/GROUP and /SYSTEM qualifiers, respectively): 


$ DEFINE LNKSLIBRARY DBA1: [GOLD] MINE1 

S DEFINE LNKSLIBRARY 1 DBA1: [GOLD] MINE2 

$ DEFINE/GROUP LNKSLIBRARY DBA1: [PROJX] PROJECTX 
$ DEFINE/SYSTEM LNKSLIBRARY SYSSLIBRARY:MYSITE 


Note that the logical names in each table must be used consecutively 
(LNKSLIBRARY, LNKSLIBRARY 1, LNKSLIBRARY 2, eee) In the preceding 
example, if you were to delete LNKSLIBRARY from the process’ logical 
name table, the linker would not search for LNKSLIBRARY 1 in the 
process logical name table, because it proceeds to the next table as 
soon as logical name translation fails. 
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3.4 DEFAULT SYSTEM LIBRARY 


If any unresolved strong references remain after the linker has 
processed all your input, it begins a search of the default system 
library. This "library" is in fact two files: one a shareable image 
called VMSRTL (default file specification is SYSSLIBRARY: VMSRTL.EXE) 
and the other an object library called STARLET (default file 
specification is SYSSLIBRARY:STARLET.OLB). 


3.4.1 VMSRTL 


If the linker needs to search the default system library, it searches 
the VMSRTL shareable image first. This shareable image contains most 
of the procedures described in the VAX-11 Run-Time Procedure _ Library 
Reference Manual, including many routines required by almost all high 
level language programs. 





If the linker finds no symbols that it needs in the shareable image, 


it does not include the shareable image VMSRTL in the image being 
created. 


You can use the /NOSYSSHR qualifier with the LINK command to’ suppress 
the linker's search of VMSRTL (see Chapter 4). 


3.4.2 STARLET 


STARLET is an object module library. It contains all the object files 
used to create the shareable image version of the Run-Time Library, as 
well as other less frequently used procedures. This object library 
also contains modules for interfacing to VAX/VMS system services. 


The linker searches STARLET if any unresolved strong references remain 
after it has searched VMSRTL. 


You can use the /NOSYSLIB qualifier to the LINK command to suppress 
the linker's search of both STARLET and VMSRTL (see Section 4.2.1). 


3.5 EXAMPLE OF USING LIBRARIES 
The following example shows how you can specify both explicit and 
implicit inclusion of modules from libraries. (Assume that there are 
no user-defined default libraries.) 
$ LINK LAUREL,HARDY- 
MINE2/INCLUDE=MODULEZ,- 
MINE3/LIBRARY 
These statements tell the linker: 
1. Link the object modules LAUREL and HARDY. 


2. Extract MODULEZ from the library MINE2 and link it with the 
object modules LAUREL and HARDY. 
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3. If any unresolved strong references remain in LAUREL, HARDY, 
or MODULEZ, search the library MINE3, and extract and link 
any modules needed to resolve these references. 


4. For any strong references that are still unresolved, search 
the default system library. 


Note that the linker will not search MINE3.OLB and the default system 
library if the only unresolved references are weak references. For a 
discussion of weak references, see Section 2.2.2.4. 


CHAPTER 4 


THE LINK COMMAND 


To invoke the VAX-11 Linker, use the DIGITAL Command Language (DCL) 
LINK command. You can enter the LINK command interactively, or you 
can include it in a command procedure. 


The LINK command recognizes a number of command qualifiers and file 
qualifiers. A command qualifier conveys information about the linking 
operation and the image to be created -- for example, whether to 
generate an image map, or whether to include a debugger in the image. 
A file qualifier specifies information about a file that is input to 
the linker -- for example, identifying the file as a library. Some 
qualifiers are valid only if they are used with other qualifiers, and 
some qualifiers are incompatible with other qualifiers. 


This chapter discusses the LINK command and its qualifiers, but 
discusses command syntax only where necessary to avoid errors or 
misunderstanding. For detailed information on command syntax, see the 
VAX/VMS Command Language User's Guide. 





4.1 COMMAND FORMAT 
The LINK command is usually entered in the following format: 
§ LINK/command-qualifier... file-spec/file-qualifer,... 


You must enter at least the LINK command name and one input file name. 
You can enter multiple command qualifiers and file specifications, and 
one or more file qualifiers for each file specification. 


Slashes (/) separate qualifiers from each other and from the command 
name or file specification with which they are associated. One or 
More spaces or tabs must separate the last command qualifier from the 
first input file specification. A comma must precede the second and 
subsequent input file specifications. 


The following examples show some acceptable formats of the LINK 
command (Section 4.3 explains these examples). 


$ LINK PROGA 
$ LINK/MAP/DEBUG PAYROLL,FICA,PAYLIB/LIBRARY 
$ LINK/MAP/FULL/EXECUTABLE=STOOGES CURLY ,- 


LARRY ,MOE, TVLIB/INCLUDE=OLDIES,- 
COMEDY/LIBRARY ,SLAPSTICK/OPTIONS 
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The names assigned to the image file, the map file, and other output 
files depend on the first input file name, unless you specify 
differently. You can specify a different output filename by 
specifying a name in an /EXECUTABLE, /SHAREABLE, /MAP, or 
/SYMBOL TABLE qualifier or by entering one of these qualifiers after a 
file specification (see Section 4.2). In the second of the preceding 
examples, the image file and the map file will be named PAYROLL. In 
the third example, the image file will be named STOOGES because you so 
specified with the /EXECUTABLE qualifier, but the map file will be 
named CURLY. (To name the map file STOOGES, you must specify 
/MAP=STOOGES. ) 


4.2 COMMAND AND FILE QUALIFIERS 


You can enter many command and file qualifiers, but normally you will 
not need to because most qualifiers have default values that the 
linker uses if you omit the qualifier. 


Some qualifiers are incompatible with certain other qualifiers. The 
linker takes one of two actions if you specify incompatible 
qualifiers: either it invalidates the entire LINK command and 
displays an error message, or it ignores certain qualifiers 
(generally, all except the last valid one) and allows the link to 
continue. For example, if you specify /FULL and /BRIEF for the map, 
the linker rejects the entire command; but if you specify the 
positive and negative forms of a qualifier (say, /EXECUTABLE and 
/NOEXECUTABLE), the linker accepts the last one entered. 


Tables 4-1 and 4-2 list the command and file qualifiers, the default 
value for each command qualifier, the function for each file 
qualifier, and incompatible qualifiers. A [NO] indicates that the 
qualifier can be negated by prefixing NO (without brackets) -- for 
example, /NODEBUG or /NOEXECUTABLE. Any entry after a negative 
qualifier is not valid; for example, it would be nonsense to enter 
/NOEXECUTABLE=PAYROLL. 


Sections 4.2.1 and 4.2.2 discuss the command qualifiers and file 
qualifiers individually. Within each section the qualifiers are 
presented in alphabetical order. 
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Table 4-1 
Command Qualifiers 









Command Qualifier 


























/BRIEF 


/ [NO] CONTIGUOUS 
/[NO]CROSS_ REFERENCE 


/ [NO] DEBUG [=file-spec] 


/ [NO] EXECUTABLE [=file-spec] 
/FULL 

/HEADER 

/{NO] MAP [=file-spec] 

/PO IMAGE 


/PROTECT 

/ (NO] SHAREABLE[=file-spec] 
/{NO]SYMBOL_ TABLE [=file-spec] 
/{NO]SYSLIB 


/(NO]SYSSHR 


/ (NO] SYSTEM [=base-address] 


/(NO] TRACEBACK 





/ [NO] USERLIBRARY [=(table[,...])] 







Default 


Incompatible 
Qualifiers 





Default map 


/NOCONTIGUOUS 
/NOCROSS_REFERENCE 


/NODEBUG 


/ EXECUTABLE 


Default map 


/NOMAP (interactive) 


/MAP (batch) 


/NOSHAREABLE 


/NOSYMBOL_ TABLE 
/SYSLIB 
/SYSSHR 


/NOSYSTEM 


/ TRACEBACK 


/USERLIBRARY=ALL 


/NOMAP ,/FULL, 
/CROSS_REFERENCE 


/NOEXECUTABLE 
/NOMAP ,/BRIEF 
/NOTRACEBACK, 
/SHAREABLE,/SYSTEM, 
/NOEXECUTABLE 
/SHAREABLE 


/NOMAP , /BRIEF 


/SYSTEM, 
/EXECUTABLE 


/SYSTEM, 


/DEBUG, 
/ EXECUTABLE 


/NOSYSLIB 


/DEBUG, 
/SHAREABLE 
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Table 4-2 
File Qualifiers 

















File Qualifier Function 





/INCLUDE=module-name[,...]| Includes one or 
more object modules 
from a library in 


the link 


/LIBRARY Identifies an 
object module 
library 

/OPTIONS Identifies a 


linker options 
file 
/SELECTIVE SEARCH Includes only 
global symbols 
referred to by 
previously named 
input files 


Identifies a 
shareable image 
input file; valid 
only in a linker 
options file 


/SHAREABLE [=[NO] COPY] 














Incompatible 
Qualifiers 


All others, 
/ LIBRARY 


except 


All others, 
/INCLUDE 


except 


All others 


All others, 
/SHAREABLE 


except 


All others, except 
/SELECTIVE SEARCH 





4.2.1 


Command Qualifiers 
/BRIEF 


/BRIEF produces a brief form of the 
contains only the following sections: 


image 


e Object Module Synopsis 
e Image Synopsis 


e Link Run Statistics 


map. A brief 


map 


A brief map does not contain the Program Section Synopsis and the 
Symbols by Name sections, which are included in the default map. 


/BRIEF is valid only if you also specify /MAP in the LINK 
command. /BRIEF is incompatible with /FULL and /CROSS_REFERENCE.. 


For illustrations and explanations of the image map sections, see 
Section 6.2. 
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/CONTIGUOUS 
/NOCONTIGUOUS 


/CONTIGUOUS forces the entire image to be placed in consecutive 
disk blocks. If sufficient contiguous space is not available on 
the output disk, the linker reports the error and terminates’ the 
link operation without generating an image. 


You can use the /CONTIGUOUS qualifier to improve paging 
performance for all types of images because an image uSually runs 
slower if it is not contiguous. You can also use the /CONTIGUOUS 
qualifier to satisfy the requirement of bootstrap programs for 
certain system images, since many bootstrap programs cannot 
handle discontiguous images. 


Tf you do not’ specify /CONTIGUOUS, the linker assumes 
/NOCONTIGUOUS by default. That is, if sufficient contiguous 
space is not available, the image is divided and placed in 
different areas on disk. (However, the operating system still 
tries to make the image as close to contiguous as possible.) 


/CROSS_REFERENCE 
/NOCROSS_REFERENCE 


/CROSS_REFERENCE causes the Symbols by Name section of the image 
map to be replaced by a Symbol Cross Reference section, which 
lists global symbols in alphabetical order and the _ following 
information about each symbol: 


e Its value 
e The name of the first module that defines it 
e The name of each module that refers to it 


The number of symbols listed in the cross reference depends. on 
whether you specified /FULL for the map or accepted the default 
map. A full map contains global symbols from all modules in the 
image, including modules extracted from libraries. The default 
map generally excludes global symbols that are defined and 
referred to only within the default system library. 


/CROSS_REFERENCE is valid only if you also specify /MAP in the 
LINK command. /CROSS_REFERENCE is incompatible with /BRIEF. 


If you do not request a cross reference, none is’ provided; the 
map still lists global symbols in alphabetical order, but gives 
only the value for each one. 


/DEBUG {=file-spec] 
/NODEBUG 


/DEBUG tells the linker to bind a debugging module into’ the 
image. When the image is run, the debugger receives control 
first. /DEBUG does not have any effect on the location of code 
within the image; the image map is the same with /DEBUG or 
/NODEBUG. 


If you specify /DEBUG, you can also enter the file specification 
of a user-written debug module. If you enter a debugging module 
file specification without specifying the file type, the linker 
assumes OBJ. 
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If you specify /DEBUG without entering a file specification, the 
linker uses the VAX-11 Symbolic Debugger. This debugger includes 
a debug symbol table (discussed in Section 2.3) and coding logic 
to help in debugging the image at run time. For further 
information, see the VAX-11 Symbolic Debugger Reference Manual, 





/DEBUG automatically includes /TRACEBACK. If you specify /DEBUG 
and /NOTRACEBACK, the linker overrides your specification and 
includes traceback information. 


If you do not specify /DEBUG, the linker assumes /NODEBUG. 


/EXECUTABLE [=file-spec] 
/NOEXECTABLE 


/EXECUTABLE tells the linker to create an executable image, as 
opposed to a shareable image or a system image. You can also 
enter a file specification for the image; however, if you do not 
enter one, the linker uses the file name of the first input file 
or if you specify /EXECUTABLE after an input file specification, 
the name of the modified file. If you do not enter a file type 
after the filename, the linker assumes a file type of EXE. 


If you specify both /SYSTEM and /EXECUTABLE, the linker creates a 
system image but uses the /EXECUTABLE qualifier to determine the 
image's file-specification. 


/NOEXECUTABLE tells the linker to perform all the actions 
involved in creating an executable image, but not to output it. 
You can use /NOEXECUTABLE to test combinations of files and 
qualifiers without actually creating an image. 


If you do not specify /NOEXECUTABLE, /SHAREABLE, or /SYSTEM, the 
linker assumes /EXECUTABLE. 


/FULL 


/PULL produces the most complete map of the image. The full map 
contains all the sections found in the default map, although 
several sections contain more detailed information. The full map 
also contains two sections not found in the default map. The 
following sections of a full map contain information about all 


modules in the image. (In the default map, these sections 
generally omit information about modules from the default system 
library.) 


e Object Module Synopsis 
@ Program Section Synopsis 
e Symbols by Name 


The following sections are included in a full map, but not in the 
default map: 


e Image Section Synopsis 
e Symbols by Value 


For illustrations and explanations of the image map sections, see 
Section 6.2. 


/FULL is valid only if you also specify /MAP in the LINK command. 
/FULL is incompatible with /BRIEF but not with /CROSS_ REFERENCE. 


THE LINK COMMAND 


/HEADER 


/HEADER is used with /SYSTEM; it tells the linker to create a 
system image with a header. If you specify /SYSTEM without 
/HEADER, the linker creates a system image without a header. 
Executable and shareable images always have image headers; 


consequently, /HEADER is ignored in LINK commands creating these 
images. 


/MAP [=file~spec] 
/NOMAP 


/MAP causes the linker to create an image map as a separate file. 
You can enter a file specification for the image map file; 
however, if you do not enter one, the linker uses the file name 
of the first input file or, if you specify /MAP after an input 
file specification, the name of the modified file. If you do not 


enter a file type after the file name, the linker assumes a file 
type of MAP. 


If you enter /MAP, you can further specify the contents of the 
map with the /BRIEF, /FULL, and /CROSS_REFERENCE qualifiers. If 
you enter /MAP and no related qualifier, the linker produces a 
default map that contains the following sections: 


e Object Module Synopsis 

@e Program Section Synopsis 
e Symbols by Name 

e Image Synopsis 

e Link Run Statistics 


For illustrations and explanations of the image map sections, see 
Section 6.2. 


If you do not specify /MAP, the default for interactive mode is 
/NOMAP; that is, the linker does not generate an image map. In 
a batch job the default is /MAP; that is, the linker generates 
its standard (default) map. 


/POIMAGE 


/POIMAGE is used to create executable images that modify Pl 
address space. The linker places the stack and RMS buffers that 
usually go in Pl address space in PO address’ space. See the 
VAX-11 Architecture Handbook for a description of PO and Pl 
address space. 


/PROTECT 


/PROTECT is used with /SHAREABLE; it tells the linker to protect 
the shareable image, making it a privileged shareable image. A 
privileged shareable image can execute change mode instructions 
even when it is linked into a nonprivileged executable image. 
See the VAX/VMS Real-Time User's Guide for more information on 
privileged shareable images. 
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/SHAREABLE [=file-spec] 
/NOSHAREABLE 


/SHAREABLE tells the linker to create a shareable image, (For an 
explanation of shareable images, see Section 7.6.2 and Chapter 
8.) You can also enter a file specification for the shareable 
image; however, if you do not enter one, the linker uses the 
file name of the first input file or, if you specify /SHAREABLE 
after an input file specification, the name of the modified file. 
If you do not enter a file type after the file name, the linker 
assumes a file type of EXE. 


You cannot run a shareable image, but you can link it with object 
modules or other shareable images. (See the explanation of the 
/SHAREABLE file qualifier in Section 5.1.2.) 


If you specify /SHAREABLE, you cannot specify /SYSTEM or /DEBUG. 
If you specify both /SHAREABLE and /EXECUTABLE, the linker 
ignores /EXECUTABLE and creates a shareable image. 


If you do not specify /SHAREABLE, the linker assumes 
/NOSHAREABLE; that is, the image is not a shareable image. (See 
the explanation of the /EXECUTABLE command qualifier in this 
section.) 


/SYMBOL TABLE [=file-spec] 
/NOSYMBOL_ TABLE 


/SYMBOL TABLE tells the linker to create a separate file, with a 
default file type of STB, containing the image's global symbol 
table. This qualifier does not affect the global symbol table in 
the image itself; rather, it causes an additional global symbol 
table to be created in object module format. You can also’ enter 
a file specification for the global symbol table file; however, 
if you do not make this entry, the linker uses the name of the 
first input file or, if you specify /SYMBOL TABLE after an input 
file specification, the name of the modified file. 


You can include the symbol table file as input to future linking 
operations, just as if it were an object module. For further 
information, see Section 2.3.1. 


T— you do not specify /SYMBOL TABLE, the linker assumes 
/NOSYMBOL TABLE; that is, it does not generate a symbol table 
file. ~ 


/SYSLIB 
/NOSYSLIB 


/SYSLIB tells the linker to search the default system library for 
unresolved strong references to global symbols after it has 
searched any specified user libraries and any user-defined 
default libraries. (Section 3.4 explains the default system 
library.) You will probably want the linker to search the default 
system library for almost all linking operations. If you do not 
specify /NOSYSLIB, the linker assumes /SYSLIB by default. 


/NOSYSLIB tells the linker not to search the default system 
library (VMSRTL.EXE and STARLET.OLB). You should specify 
/NOSYSLIB only if you know that other specified libraries allow 
the linker to resolve all symbolic references and if you have a 


good reason for suppressing the system library search. If you 
specify both /NOSYSLIB and /SYSSHR, the /SYSSHR qualifier is 
ignored. 
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/SYSSHR 
/NOSYSSHR 


/SYSSHR tells the linker to search the default system run time 
library shareable image (VMSRTL.EXE) for unresolved’ strong 
references to global symbols. If any symbol within this 
shareable image resolves an outstanding reference, the shareable 
image is included in your program as the highest-addressed part 
of the program region. 


The primary use of this qualifier, however, is in its negative 
form. /NOSYSSHR tells the linker not to try to resolve symbolic 
references by including the default system shareable image. 
Instead it directs the linker to use only the default object 
library (STARLET.OLB), which includes all the routines in VMSRTL. 
To tell the linker to search neither the default system shareable 


image nor the default system object library, use the /NOSYSLIB 
qualifier. 


/SYSTEM [=base-address] 
/NOSYSTEM 


/SYSTEM tells the linker to create a system image. (For an 
explanation of system images, see Section 7.6.3.) You can also 
specify a base address at which the system image will be loaded 
at run time, and you can express this address in decimal (%D), 
hexadecimal (%X), or octal (%0) format. If you specify /SYSTEM 
without a base address, the linker assumes %X80000000. The 
linker uses the filename of the first input file and the file 
type EXE. If you want a different output file-specification, you 
must also specify /EXECUTABLE, 


If you specify /SYSTEM, you cannot specify /SHAREABLE or /DEBUG. 


If you do not specify /SYSTEM, the linker assumes /NOSYSTEM; 
that is, the image is not a system image. (See the explanation 
of the /EXECUTABLE command qualfier in this section.) 


/ TRACEBACK 
/NOTRACEBACK 


/TRACEBACK tells the linker to include traceback information in 
the image. Traceback is a facility that automatically displays 
information from the call stack when a fatal program error 
occurs. The output shows which modules were called before the 
error occurred. 


The linker assumes /TRACEBACK unless you exclude the facility by 
specifying /NOTRACEBACK. If you enter /DEBUG, the linker 
automatically includes traceback also; therefore, if you specify 
both /DEBUG and /NOTRACEBACK, you receive a warning that 
/NOTRACEBACK has been ignored, 


/USERLIBRARY [=(table[,...])] 
/NOUSERLIBRARY 


/USERLIBRARY tells the linker to search any user-defined default 
libraries after it has searched any specified user libraries. 
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The linker searches the process, group, and system logical name 
tables to find the file specifications of the user-defined 
libraries. (Section 3.3 explains user-defined default 
libraries.) You can specify the following tables that you want 
the linker to search: 


ALL The linker Searches the process, group, and system 
logical name tables for user-defined library 
definitions. 

GROUP The linker searches the group logical name table for 


user-defined library definitions. 


NONE The linker does not search any logical name table; 
/USERLIBRARY=NONE is equivalent to /NOUSERLIBRARY. 


PROCESS The linker searches the process logical name table for 
user-defined library definitions. 


SYSTEM The linker searches the system logical name table _ for 
user-defined library definitions. 


If you do not specify either /NOUSERLIBRARY or 
/USERLIBRARY=(table), the linker assumes /USERLIBRARY=ALL by 
default. 


/NOUSERLIBRARY tells the linker not to search any user-~defined 
default libraries, 


4.2.2 File Qualifiers 
/INCLUDE=module-name[,...] 


“INCLUDE tells the linker to include the named module or modules 
from the associated library in the image. To specify more than 
one module, enclose the list in parentheses and separate module 
names with commas. /INCLUDE does not cause the linker to search 
the rest of the associated library for unresolved references, 
unless you also specify /LIBRARY. For further information on 
libraries, see Chapter 3. 


The following two examples show uses of the /INCLUDE qualifier 
with a library named NATIONAL that contains many modules, among 
them REDS, DODGERS, and PHILS. 


$ LINK LEAGUE,NATIONAL/INCLUDE=(REDS, DODGERS, PHILS) 


This example tells the linker to extract modules REDS, DODGERS, 
and PHILS from the library NATIONAL and include them in the 
executable image which will be named LEAGUE (since that is’ the 
name of the first input file). 


$ LINK LEAGUE,NATIONAL/LIBRARY/INCLUDE=(REDS ,DODGERS, PHILS) 
This example also tells the linker to include REDS, DODGERS, and 
PHILS in LEAGUE. However, the /LIBRARY qualifier tells the 
linker to search the rest of the library NATIONAL and link in any 
other modules needed to resolve strong symbolic references’ in 
LEAGUE, REDS, DODGERS, and PHILS. 
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/ LIBRARY 


/LIBRARY identifies a file as a library. The linker searches 
libraries that you specify if any unresolved strong symbolic 
references between modules remain after it links the previously 
named input files and any previously named library modules 
specified with the /INCLUDE qualifier. For further information 
on libraries, see Chapter 3. 


/LIBRARY cannot be the only qualifier on the first input file, 


since there are as yet no outstanding references to he resolved 
from this library. 


/OPTIONS 


/OPTIONS identifies a file as a linker options file. This file 
can contain input file specifications, as well as_ special 
instructions recognized only by the linker and not by the command 
interpreter. 


Chapter 5 explains how to create an options file and what it can 
contain. Chapter 5 also discusses each of the _ special 
instructions you can include in the options file. 


/SELECTIVE SEARCH 


/SELECTIVE SEARCH tells the linker to include in the image's 
global symbol table only those global symbols in the associated 
file that previously named input files refer to. If you do not 
specify /SELECTIVE SEARCH for an input file, all of its global 
symbols are included in the global symbol table of the image. 


/SHAREABLE [=[NO] COPY] 


4.3 


/SHAREABLE as an input file qualifier is valid only within a 
linker options file. Section 5.1.2 explains the use of the 
/SHAREABLE file qualifier. 


EXAMPLES 
1. $ LINK PROGA 


The linker binds the object module PROGA and creates an 
executable image named PROGA. The linker searches any 
user-defined default libraries and the default system library 
for any unresolved strong symbolic references in PROGA.OBJ. 
All linker defaults are used. 


2. $ LINK/MAP/DEBUG PAYROLL,FICA,PAYLIB/LIBRARY 


The linker binds object modules PAYROLL and FICA, searching 
the library PAYLIB’ for unresolved strong references in the 
two object modules before searching any user-defined default 
libraries or the default system library. The linker also 
includes the VAX-11 Symbolic Debugger in the image. 


The name of the executable image is PAYROLL. The linker also 
generates an image map (in the default map format) with a 
file name of PAYROLL and a file type of MAP. 


3. 
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$ LINK/MAP/FULL/EXECUTABLE=STOOGES CURLY ,- 
LARRY ,MOE, TVLIB/INCLUDE=OLDIES ,- 
COMEDY/LIBRARY ,SLAPSTICK/OPTIONS 


The linker binds object modules CURLY, LARRY, and MOE, as 
well as the module OLDIES from the library TVLIB. The linker 
searches the library COMEDY for any unresolved symbolic 
references in CURLY, LARRY, MOE, and OLDIES, before searching 
any user-defined default libraries or the default system 
library. The linker uses the options file SLAPSTICK for 
additional input file specifications or special instructions. 


The linker generates a full map, with the default file name 
of CURLY and the file type of MAP. The executable image is 
named STOOGES. 


CHAPTER 5 


THE /OPTIONS FILE QUALIFIER 


The /OPTIONS file qualifier identifies a linker options file. You can 
include two types of information in this file: 


@ Input file specifications and associated file qualifiers, in 
addition to any that you enter in the LINK command itself 


e Special instructions to the linker that are not available 
through the DCL command language 


When you specify an options file at link time, the linker reads’ the 
file before performing the linking operation. 


5.1 USES FOR AN OPTIONS FILE 


You can create an options file and use the /OPTIONS qualifier for a 
number of reasons: 


e To give the linker a series of file specifications and file 
qualifiers that you use frequently in linking operations 


e To identify a shareable image as an input file to the link 
operation 


e To enter a longer list of files and file qualifiers than the 
VAX/VMS command interpreter can hold in its command input 
buffers 


e To specify information that applies only to LINK and to no 
other command 


5.1.1 Entering Frequently Used Input Specifications 


You can create an options file containing a group of file 
specifications and file qualifiers that you link frequently, and you 
can specify this options file as input to the linker. The advantages 
of this method are convenience and flexibility. Consider the 
following two examples. 


1. You want to create an executable image named PAYROLL 
containing modules named PAYCALC, FICA, FEDTAX, STATETAX, and 
OTHERDED. You also want to be able to make changes to any of 
the modules and conveniently relink the image. 


To accomplish these goals, you can use the EDIT or CREATE 
command to create the file PAYROLL.OPT containing the file 
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specifications of the five modules. Then, to link the image 
initially or to relink it any time thereafter, you can simply 
enter SLINK PAYROLL/OPTIONS, instead of having to enter the 
/EXECUTABLE=PAYROLL qualifier and the file specifications of 
all the input modules each time. (Note that using the 
options file in this example produces an image named 
PAYROLL.) The more file specifications and file qualifiers 
that you need to link an image, the greater is the 
convenience of using an option file. 


2. Two programmers, one writing PROGX and the other PROGY, both 
need to include the modules MODA, MODB, and MODC, and to 
search the library LIBZ. Someone can create an options file 
(say, [G15]GROUP15.OPT) containing the file specifications 
for MODA, MODB, and MODC, and the specification for LIBZ 
followed by /LIBRARY. At link time, then, each programmer 
needs to specify only the name of his or her module and _ the 
options file-- for example: 


$ LINK/MAP PROGX, [G15] GROUP15/OPTIONS 


5.1.2 Identifying A Shareable Image As Input 


To identify a shareable image as an input file to the linker, you must 
use the /SHAREABLE file qualifier within an options file. (If you 
include /SHAREABLE in the LINK command, the linker assumes that it is 
a command qualifier, not an input file qualifier.) 


The format for /SHAREABLE as an input file qualifier is as follows: 
/SHAREABLE [= [NO] COPY] 


@ /SHAREABLE identifies the associated input file as a shareable 
image. 


e You can optionally specify COPY or NOCOPY as’ keywords. COPY 
causes the linker to produce a private copy of the shareable 
image in the image being created. NOCOPY, which is’ the 
default, causes the linker not to produce a private copy. 


5.1.3 Entering More Input Than The Command Language Can Handle 


At times you may need to link a series of input files and file 
qualifiers that exceeds the buffer capacity of the command interpreter 
(255 characters). The maximum number of entries depends on the length 
ef the specific entries themselves and how much of each line you use. 
However, aS a general guideline, if your LINK command = statement 
exceeds six or seven lines, the command interpreter may not be able to 
process it. In this case, you must put some or all of the input file 
specifications and file qualifiers in an options file. 


5.1.4 Entering Non-standard Link Instructions 


The linker is more complex than most VAX/VMS utilities; it can 
perform a number of optional functions in creating an image. Although 
the LINK command could have been designed to accept a very large 
number of command qualifiers, some of these optional functions are not 
frequently used and apply only to the linker -- for example, 
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specifying the image's base address or the number of I/O channels it 
can use. 


Therefore, to keep the size of the command interpreter's internal 
tables and code to a manageable level, the /OPTIONS qualifier was 
developed. /OPTIONS is recognizable to the command interpreter, but 
the special functions that the options file can specify are 
recognizable only to the linker. When you specify an options file, 
then, the command interpreter passes the file to the linker, which 
reads and interprets its contents. 


Table 5-1 lists the special functions that you can request only in an 
options file, giving the following information for each: its format, 
the default value (if applicable), and a brief explanation. Section 
5.3 provides detailed explanations of each special function. 


Table 5-1 
Special Options 


































Default 








Format Explanation 








%X200 for executable 
and shareable 
%X80000000 for 
system 


Base virtual 
address for the 
image 


CHANNELS=n Maximum number of 
I/O channels the 
image can use 
during execution; 
reserved for future 
use 





128 (See Section 5.3) 


CLUSTER=cluster-name,- 
[base-address],- 
[pfc],file-spec[,...] 


Defines a 
cluster 


(See explanation 
in Section 5.3.) 





Moves the named 
program sections to 
the specified 
cluster 


COLLECT=cluster-name ,- 
psect-name[,...] 


DZRO_MIN=n Minimum number of 
uninitialized pages 
before demand zero 
compression can 


occur 









GSMATCH=keyword,- 
major-id,minor-id 


EQUAL ,x,Y 
(see Section 5.3) 


Sets match control 
parameters of a 
shareable image 





IOSEGMENT=n, - 
[ [NO] POBUFS] 


32, POBUFS 





Number of pages for 
the image I/0 
segment 





Maximum number of 
image sections 


Approximately 96 
(See Section 5.3) 


ISD_MAX=n 





(continued on next page) 


THE /OPTIONS FILE QUALIFIER 


Table 5-1 (Cont.) 
Special Options 





Format Default 





Explanation 















PROTECT= Nock 


NO NO Specifies protected 


clusters when 
creating a 
shareable image 


PSECT_ATTR=psect—name,- Specifies the 
attribute[,...] attributes of a 
program section 


STACK=n 20 Initial number of 
pages for the user 
mode stack 


SYMBOL=name, value Defines the named 
symbol as global 

and assigns it a 

value 


UNIVERSAL=symbol-name Identifies a global 
[pee] symbol as universal 





5.2 CREATING AND SPECIFYING AN OPTIONS FILE 


To use the /OPTIONS qualifier, you must first create the options file. 
Use the EDIT command, specifying any valid file name and a file type 
of OPT. (You can use any file type, but the linker uses a default 
file type of OPT with the /OPTIONS qualifier.) 


The options file can contain input file specifications and associated 
file qualifiers, or the special link options outlined in Table 5-1, or 
both types of information. The following rules apply to the contents 
of a linker options file: 


1. You must enter any input file specifications and associated 
file qualifiers before any special options [see Table 5-1 for 
the available special options). The input file 
specifications must be on the first line of the options file 
or on a continuation of the first line and must be’ separated 
by commas. 


2. You cannot enter command qualifiers. 
3. You cannot enter the /OPTIONS file qualifier. 


4. You can enter /SHAREABLE as an input file qualifier only in 
an options file (see Section 5.1.2). 


5. You cannot enter more than one special option on a line. 


6. You can continue a file specification line or a_ special 
option line. 
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7. You can enter comments after an exclamation point (!). 


8. You can shorten the name of a special option, as long as you 
enter at least the first four characters (for example, 
CHAN=50 instead of CHANNELS=50). 


The following example shows a file named PROJECT3.OPT that contains 
both input file specifications and special options: 


PROJECT3.0OPT 








MOD1 ,MOD7,LIB3/LIBRARY ,- 
LIB4/LIBRARY/INCLUDE=(MODX ,MODY, MODZ) ,- 
MOD12/SELECTIVE SEARCH 

STACK=75 ~ 

SYMBOL=JOBCODE,5 





To include all the specifications and options in this example at link 


time, you need specify only the file name followed by /OPTIONS. For 
example: 


$ LINK/MAP/CROSS_REFERENCE PROGA, PROGB,- 
PROGC, PROJECT3/OPTIONS 


If you have entered the SET VERIFY command, the contents of the 
options file are displayed as the file is processed. 


You can specify one or several options files in a LINK command 
statement. 


If you want the LINK command to be in a command procedure, you can 
specify SYSSINPUT: as an options file. Otherwise the LINK command 
will be in two files. For example, a command procedure, LINKPROC.COM 
could contain the following: 


$ LINK MAIN,SUB1,SUB2,SYSSINPUT: /OPTIONS 
MYPROC/SHAREABLE 

SYSS$ LIBRARY : APPLPCKGE/SHAREABLE 

STACK=75 

5. 


5.3 SPECIAL OPTIONS 


This section lists the available special options in alphabetical order 
and explains each one. Each option has the general format: 


option_name=parameter[,...] 


If the parameter is a number (indicated by "n"), you can express it in 
decimal (%D), hexadecimal (%X), or octal (%0) format. The default and 
maximum numeric values in this manual are expressed in decimal, as are 
the values in any linker error or warning messages relating to these 
options. 


BASE=n 
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BASE= specifies the base virtual address of the default 
cluster. If you do not define any clusters with the CLUSTER= 
option, the BASE= option value also specifies the base virtual 
address of the whole image. If you specify an address that is 
not divisible by 512, the linker automatically adjusts it 


upward 


to the next multiple of 512 (that is, the next highest 


page boundary). 


The default base address is hexadecimal 200 (decimal 512) for 
executable and shareable images, and hexadecimal 80000000 for 
system images. 


CHANNELS=n 


CHANNELS= specifies the maximum number of I/0 channels” that 
the image can use while it is running. This option is 
currently ignored by the linker. All images have a maximum of 
128 channels. 


CLUSTER=cluster-name, [base-address], [pfc],file-spec[,...] 


CLUSTER= defines a cluster. Clusters are discussed in 
Chapters 7 and 8. The CLUSTER= option specifies the following 


information: 
e The name the linker will assign to it 
e Optionally, the base virtual address of the cluster 
e Optionally, the page fault cluster (pfc) -- that is, 
the number of pages to be read into memory when a 
fault occurs for a page in the cluster 
e Specifications for the file or files that the linker 
is to use in creating the cluster. Note that you 
should not specify in the LINK command itself any 
files that you specify with the CLUSTER= option 
(unless you want two copies of each file included in 
the final image). 
If you omit the base address or the page fault cluster, or 


both, 


you must still enter the comma after each omitted 


parameter. For example: 


CLUSTER=AUTHORS,, , TWAIN, DICKENS 


The linker uses the following defaults in connection with the 
CLUSTER= option: 


If you do not use the CLUSTER= option, the linker 
creates a default cluster, as described in Section 
7.9. 


If you use the CLUSTER= option but do not specify a 
base address, the linker allocates the cluster 
according to the procedure described in Section 7.9. 


If you use the CLUSTER= option but do not specify a 
page fault cluster, VAX/VMS memory management 
determines the value. 
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COLLECT=cluster-name,psect-name[,...] 


COLLECT= causes the named program sections to be placed in the 


specified cluster. If the cluster name is also used in a 
CLUSTER= option, the named program sections are added to that 
defined cluster. If the cluster name is not also used in a 


CLUSTER= option, the COLLECT= option defines the cluster. 


The COLLECT= option can only specify program sections defined 
with the GBL attribute. 


The COLLECT= option cannot specify any program sections that 
are defined in shareable images. 


DZRO_MIN=n 


DZRO_MIN= is an option that gives you some control over the 
linker's compression of uninitialized pages in an executable 
image. Before the linker writes the binary data and code of 
the image, it attempts to compress certain uninitialized areas 
by converting them to demand zero image sections. ("Demand 
zero" means that although an area does not occupy physical 
space in the image on disk, when the area is accessed during 
execution, a portion of memory is allocated for it and 
initially filled with binary zeroes.) An uninitialized area 
is eligible for this compression if it can be written in by 
the user and if its size is equal to or greater than a 
threshold value: that is, the DZRO MIN= value. The linker 
will not, however, continue creating demand zero’ sections 
after the total number of image sections reaches the maximum 
(see the ISD MAX= option in this section). 


The default value for DZRO_ MIN= is 5; that is, an 
uninitialized, writeable area is not eligible for compression 
unless it occupies five or more contiguous pages. A DZRO_MIN= 
value less than 5 might (depending on the contents of the 
object modules) cause the linker to compress more sections and 
create a greater number of image sections, possibly reducing 
the image size on disk but decreasing its paging performance. 
A value greater than 5 might cause the linker to compress 
fewer sections and create a smaller number of image sections, 
possibly increasing the image size on disk but providing 
better performance during execution. 


GSMATCH=keyword,major—id,minor~id 


GSMATCH= sets the match control parameters for a_ shareable 
image that you are now creating. After the shareable image 
has been linked with an executable image, and when the 
executable image is being run, these parameters guide the 
VAX/VMS image activator in choosing global sections. For 
further information on this process, see Section 8.3.2. 


The GSMATCH= option specifies the following information: 


e A keyword expressing the match relationship between 
the minor identifications in the user shareable image 
section and in the installed global section. This 
keyword is one of the following: 


- EQUAL The minor identification of the user 
shareable image section must be identical to that 
of the installed shareable image section. 
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- LEQUAL The minor identification of the user 
shareable image section must be less than or equal 
to that of the installed shareable image section. 
LEQUAL permits the creator of a shareable image to 
update it (increasing the minor identification) and 
install it, and yet avoid the need for programs 
using that shareable image to be relinked. (The 
minor identification of that shareable image 
section in programs that are linked to it will be 
less than the minor identification of the updated 
installed shareable image section.) 


- NEVER The linker is to assume that global sections 
will never match (perhaps because the shareable 
image will never be installed). Therefore, the 
linker will always create a private copy of this 
shareable image in any image that links to it. 
(This keyword overrides any stated or defaulted 
NOCOPY keyword in the /SHAREABLE file qualifier in 
any subsequent link operation .-that names this 
shareable image as an input file.) 


- ALWAYS This keyword causes the image activator to 
match image sections by name only and to ignore the 
major and minor identifications. (However, the 
syntax of this option requires that you still enter 
major and minor identifications.) 


e The major identification of the user shareable image 
section, expressed as a number from 0 through 255, 


e The minor identification of the user shareable image 
section, expressed as a number from 0 through 2**24-1], 


The linker uses the following defaults for the GSMATCH= 
option: 


GSMATCH=EQUAL,x,y 


where "x" and "y" together are the middle 32 bits of the 
2-longword creation time that is stored in the shareable image 
file header. This default value forces user images that are 
linked to this (installed) shareable image to be relinked each 
time the shareable image is updated. To ensure that other 
users will not have to relink images that are linked to your 
shareable image whenever you modify it, specify the following 
GSMATCH= value: 


GSMATCH=LEQUAL ,0,0 
IOSEGMENT=n[, [NO] POBUFS] 


IOSEGMENT= specifies the number of pages for the image I/0 
segment, which holds the buffers and VAX-11 RMS control 
information for all files that the image's process uses. Tf 
the process needs more space than the IOSEGMENT value during 
execution, VAX-11 RMS adds space for it at the end of the 
program (P0) region. 


You can also specify POBUFS or NOPOBUFS as_ parameters. 
POBUFS, which is the default, permits RMS to use the program 
region (PO) for any additional buffers that it needs. 
NOPOBUFS denies RMS the option of using PO space for 
additional buffers. 
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The default value for IOSEGMENT= is 32,POBUFS. The only 
reason to specify a number of pages greater than the default 
is to guarantee that the program region will be contiguous if 
you need to extend it and if the total size of your program's 
buffers and VAX-11 RMS control information exceeds 32 pages. 
In this case, you also need to specify NOPOBUFS. 


ISD_MAX=n 


PROTECT= { 


ISD MAX= is an option that gives you some control over the 
linker's compression of uninitialized pages in an executable 
image. (For an explanation of compression, see the DZRO_MIN= 
option in this section.) The ISD MAX= value specifies the 
maximum number of image sections allowed in the image. If the 
linker is compressing the image by creating demand zero 
sections and the total number of image sections reaches’ the 
ISD_MAX= value, the compression ceases at that point. 


The default value for ISD MAX= is approximately 96. Note that 
any value you specify Is also an approximation. The linker 
determines an exact ISD_MAX= value based on certain 
characteristics of the image, including the different 
combinations of section attributes. The exact value, however, 
will be equal to or slightly greater than what you specify; 
it will never be less. 


vESt 
NO 


PROTECT= controls whether clusters are protected. PROTECT=YES 
specifies that all clusters defined (in a CLUSTER or COLLECT 
option) between it and the next PROTECT= option are protected. 
PROTECT=NO (default condition) specifies that all clusters 
defined between it and the next PROTECT= option are not 
protected, Protected clusters are used in privileged 
shareable images to execute privileged instructions. See _ the 
VAX/VMS Real-Time User's Guide for more information on 
privileged shareable images. 





PSECT_ATTR=psect-name,attribute[,...] 


STACK=n 


PSECT ATTR= specifies one or more attributes of the named 
program section. This option is used to change the compiled 
or assembled attributes of a program section. 


You must use the abbreviation given in Section 6.2.3 for each 
attribute. If you do not list a complete set of attributes, 
this option does not change any attributes that are not 
listed. For example, the option 


PSECT_ATTR=ALPHA,NOWRT 


can be used to make the program section ALPHA not writeable 
instead of writeable; however, all other attributes of ALPHA 
remain the same. 


STACK= specifies the initial number of pages to be allocated 
for the image's user mode stack area. If when the program is 
executed it requires more stack space than was allocated, the 
stack is automatically expanded. 


The default value is 20. 
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SYMBOL=name, value 


SYMBOL= defines "name" as an absolute global symbol with the 
specified value. The value must be expressed as a number. 


Because the linker processes special options before input file 
specifications, the name and value specified by the SYMBOL= 
option constitute the first definition of that symbol. If an 
input object module also defines that symbol, one of the 
following occurs: 


e If the object module defines the symbol as 
relocatable, that definition is ignored and _ the 
definition by the SYMBOL= option is used. A warning 
message is issued. 


e If the object module defines the symbol as absolute, 
that definition is ignored and the definition by the 
SYMBOL= option is used. No warning message is issued. 


UNIVERSAL=symbol-name[,...] 


UNIVERSAL= identifies one or more global symbols of a 
shareable image as universal symbols. For a discussion of 
universal symbols, see Section 2.2.3. 


CHAPTER 6 


IMAGE MAP 


If you so request, the linker produces an image map containing 
information about the contents of the image and about the linking 
process itself. 


To obtain a map, you must include the /MAP qualifier in the LINK 
command. You can specify a file name with the MAP qualifier, or you 
can let the linker assign a default. You can further specify the type 
of map with the /BRIEF or /FULL qualifier. If you enter either /MAP 
alone or /MAP with /FULL, you can also include a symbol cross 
reference in the map by specifying /CROSS REFERENCE. However, if you 
enter /MAP and no other map-related qualifiers, the linker generates 
its default map. 


The map is placed on your output disk and assigned a default file type 
of MAP. You can print a copy of the map with the PRINT command. 


The following examples show the LINK command qualifiers necessary to 
produce different types of maps: 


Command Qualifiers Type of Map Produced 
$ LINK/MAP/BRLIEF Brief map 
$ LINK/MAP Default map 


$ LINK/MAP/CROSS_ REFERENCE Default map with symbol 
cross reference 


§$ LINK/MAP/FULL Full map 
§ LINK/MAP/FULL/- Full map with symbol 
CROSS_REFERENCE cross reference 


6.1 IMAGE MAP CONTENTS 


A listing of the image map contains several sections; however, the 
number of sections and the contents of certain sections depend on the 
qualifiers that you enter. 


Table 6-1 lists all the possible section names in the order in which 
they appear, the types of map in which each appears, and a brief 
explanation of each section. A section shown as appearing in "all" is 
included in all types of image maps; "default" and "full" identify 
sections appearing in default and full maps, respectively. A brief 
map thus contains only the map_ sections designated as "all." For 
detailed explanations and illustrations of map sections, see Section 
6.2. 
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Table 6-1 
Image Map Sections 





Section Name Appears In Explanation 

Object Module Synopsis All Object modules in the image 

Image Section Synopsis Full Image sections and clusters 

Program Section Synopsis | Default Program sections and_ the 

Full modular contributions 

Symbols by Name Default Symbols by Name lists 

or Full global symbol names and 

Symbol Cross Reference values. However, if you 
specify /CROSS_REFERENCE, 
Symbol Cross Reference 
appears instead, listing 
symbol names, values, 
defining modules, and 
referring modules. 

Symbols by Value Full Hexadecimal symbol values 
and names’ of symbols with 
those values 

Image Synopsis All Statistics and other 
information about the 
output image 

Link Run Statistics All Statistics about the link 


run that created the image 











The contents of the following sections vary depending on whether’ the 
map type is default or full: 


@ Object Module Synopsis 

e Program Section Synopsis 
e Symbols by Name 

@ Symbol Cross Reference 


The difference between these sections in a default map and in a full 
map is in the number of items: 


e A default map generally includes only information that applies 
to modules and shareable images that you name as input to the 
linker or that are extracted from libraries you name. A 
default map normally does not list information that applies 
only to modules taken from the default system library. 


e A full map includes information that applies to all modules 
and shareable images, including those extracted from the 
default system library. 
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6.2 IMAGE MAP SECTIONS 

The rest of this chapter explains and illustrates each available image 
map section. The sections are presented in the order in which they 
appear in a full map. Brief and default maps do not have all of these 
sections, but the sections that they do have are in the order 
presented here. 

The illustrations reflect an image created from a simple FORTRAN 
program (similar to the example developed in the VAX/VMS Primer). 
Each illustration is from a full map. Headings and items in each 
illustration are explained only if they are not self-explanatory. 


Appendix B contains examples of the brief, default, and full forms of 
the image map. 


6.2.1 Object Module Synopsis 


The Object Module Synopsis lists object modules in the order in which 
the linker processed them. This section appears in all types of maps. 


The Object Module Synopsis provides the following information about 
each module listed: 


e@e Module name 

e Module identification as it appears in the module header 

@ Module length in bytes 

e Complete file specification for the module 

e Module creation date 

e Language translator that created the module 
The Object Module Synopsis also lists any errors that the linker 
detected when it wrote the binary data and code--for example, a 
warning message that a module refers to an undefined symbol. The 
message appears immediately below the line that indicates the module 


that the linker was processing when the error occurred. . 


Figure 6-1 illustrates the Object Module Synopsis section, 


6.2.2 Image Section Synopsis 

The Image Section Synopsis lists information about the image sections 
in the order in which they are mapped in the image. The Image Section 
Synopsis appears only in a full map. 


The Image Section Synopsis lists the following information about each 
image section: 


e Cluster in which the sections were allocated or found 
e Code used internally by the linker 
e Number of pages 


e Base virtual address within the image 
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® Base virtual block number within the image file on disk (zero 
indicates that the image section is not in the image file) 


@e Page Fault Cluster (PFC) (zero indicates that VAX/VMS memory 
management determines the value) 


e Protection characteristic ("read-only" or "“read/write") and 


paging information ("copy on reference," “copy always" 
(shareable images only), "demand zero," or blank for’ standard 
handling) 


e Global section name if the cluster is a shareable image 


@ Match control of global sections 
@® Major and minor identification of global sections 


Figure 6-2 illustrates the Image Section Synopsis section. 


6.2.3 Program Section Synopsis 


The Program Section Synopsis lists information about program sections 
(PSECTs), including relative addresses within the image and PSECT 
attributes. This section appears in default and full maps. 


The address information enables you to translate an address from a 
program module listing into a virtual address in the image, and vice 
versa. This ability can help you isolate errors or problems in the 
image at run time--for example, by allowing you to relate an address 
in an error message to a specific location within a specific module. 


The attributes of each program section are also listed. The linker 
considers certain attributes when it groups PSECTs into image sections 
(ISECTs). For further information on this process, see Section 7.7. 


The Program Synopsis, illustrated in Figure 6-3, lists the following 
information about each program section: 


e Program section name, in order of increasing base virtual 
addresses 


@ Name of the module or modules that contribute binary data or 
code to the program section 


@ Base and ending virtual addresses, in hexadecimal, of each 
module's contribution to the PSECT 


e Alignment for the start of each module that contributes to the 
PSECT. The number that follows the alignment description is 
the power of 2 that expresses the length in bytes. (For 
example, 2 to the power of 2 equals 4, the number of bytes in 
a longword.) The alignment column can contain these entries: 


BYTE 0 - Byte alignment (1 byte) 


WORD 1 - Word alignment (2 bytes) 
LONG 2 — Longword alignment (4 bytes) 
QUAD 3 - Quadword alignment (8 bytes) 
PAGE 9 - Page alignment (512 bytes) 

e Attributes of the PSECT. Most attributes are parts of 
contrasting pairs. Table 6-2 lists the attribute 
abbreviations (in alphabetical order), their meanings, and any 
contrasting attributes. Section 7.5.4 explains the 


attributes. 
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Table 6-2 
PSECT Attributes 











Abbreviation Meaning Contrasts With 


Absolute REL 
Concatenated OVR 
Executable NOEXE 
Global LCL 
Local GBL 
Library (from USR 
shareable image) 

Not executable EXE 
Not position- PIC 
independent code 

Not readable RD 
Not shareable SHR 
Not vectors for VEC 
privileged 

shareable image 

Not writeable WRT 
Overlaid CON 
Position-independent NOPIC 
code 

Readable NORD 
Relocatable ABS 
Shareable NOSHR 
User LIB 
Vectors for NOVEC 
privileged 


shareable image 


Writeable NOWRT 


wOGB2: [GOLDMAN] AVERAGE, EXE? 1 


Psect Name 
SPDATA 
SLOCAL 
$CODE 


aOTSSCODE 


» BLANK , 


Module Name 


AVERAGE 


AVERAGE 


AVERAGE 


OTSSLINKAGE 


OTSSLINKAGE 
SYSVECTOR 


aDBB2t [GOLDMAN] AVERAGE EXEs1 


Symbo] 


AVERAGE 


s 
FORSIO,X_DA 
FORSLINKAGE 
FORSOPEN 

e 


Value 


saecee 
B809G6BG=R 
. 
e 


e 
QBAGIGITB=RU 
BBSGG69CeR 
@G088978-RU 

e 

® 

. 
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6.2.4 Symbols By Name 


The Symbols by Name section lists global symbols in alphabetical order 
and gives the hexadecimal value of each one. The value may have one 
of the following suffixes: -R for a relocatable symbol, -U for a 
universal symbol, ~-RU for a relocatable universal symbol, -W for a 
weak definition, or -* for an undefined symbol. (The linker assigns a 
value of zero to undefined global symbols.) 


The Symbols by Name section appears only in a default or full map that 
does not have across reference. If you include /CROSS REFERENCE in 
the LINK command, the Symbols by Name section is replaced by the 
Symbol Cross Reference section. 


Figure 6-4 illustrates the Symbols by Name section. 


6.2.5 Symbol Cross Reference 


The Symbol Cross Reference’ section lists global symbols in 
alphabetical order and gives the following information about each one: 


e Hexadecimal value. The value can have one of the following 
suffixes: ~R for relocatable, -W for a weak definition, -* 
for undefined, -U for universal, or RU for’ relocatable 
universal. 


e Name of the first module that defines the symbol (blank if the 
symbol is undefined). 


e Name of each module that refers to the symbol. The name _ has 
the prefix WK- if the module makes a weak reference to the 
symbol. 


The Symbol Cross Reference section appears only in a default or full 
map for which you specify /CROSS_ REFERENCE. It replaces the Symbols 
by Name section. 


A primary value of the Symbol Cross Reference section is that it shows 
which modules are affected by each symbol. For example, if you want 
to change a symbol definition, the Symbol Cross Reference’ section 
tells you where it is defined and what other modules may be affected 
by the change. 


Figure 6-5 illustrates the Symbol Cross Reference section. 


6.2.6 Symbols By Value 


The Symbols by Value section lists the hexadecimal values of global 
symbols in ascending numeric sequence, with the symbol or symbols that 
correspond to each value. The symbol name can have one of the 
following prefixes: R- for relocatable, U- for universal, or RU- for 
relocatable universal. 


This section appears only in a full image map. 


Figure 6-6 illustrates the Symbols by Value section. 


a0BB22 (GOL 


OMAN) AVERAGE, EXE32 


Symbol Value 
AVERAGE B8eeD6ae"R 

e 

e 
FORSIO,END geaeesaseru 
FORSIO,FC,R 2220094a~RU 
FORSIO,FC,V @2000948-RU 
FORSIO,F LR 2900@8Ba-RU 
FORSIO.F.V araeeeseeRu 

. 

s 
0882 [GOLDMAN] AVERAGE. EXEs 1 
Value 
aeauvene Re AVERAGE 
aeasae9c R=BASSLINKAGE 
@eoeeeaa —«s- RU* FORSCLOSE 
08080828 =RU*FORSDECODE, MF 
@2eG0810  RU\FORSDECODE.MO 
@80R818 — RU@FORSENCODE.MF 


22-FE8=1988 14314 LINKER V2,48 


evevsesequeseenecooauvssesnst 


! Sympo! Cross Reference i} 


Peensvseeragcessaeouvqacasesy 


Defined By Referenced By eee 


AVERAGE 


VMSRTL AVERAGE 
¥MSRTL 
VeSRTL 
VMSRTL AVERAGE 
VMSRTL 


Figure 6-5 Symbol Cross Reference Section 


22-FEB=1988 14314 LINKER V82,49 


Peecoereuasseussaese4+ 


{1 Symbols By Velue | 


Pouaseuaveveuneosuessy 


SymbO1] Beee 


ReFORSLINKAGE ReOTSSLINKAGE 


Key for special characters eboves 


Fuuvaseequvevsgrssesas 


1s © Undefined 
1U @# Universe] 


i 
{ 


1R © Relocateble { 


t WK © Week 


i 


Peeouvecesaseusscesesst 


Figure 6-6 Symbols by Value Section 


Page 


Page 


a 


7 


adWW dOWWI 


IMAGE MAP 


6.2.7 Image Synopsis 


The Image Synopsis, which appears in all maps, gives miscellaneous 
information about the output image. The virtual memory allocation 
lists (in hexadecimal radix) the image's starting address, ending 
address, and total size in bytes and (in decimal radix) the total size 
in bytes and pages. The other items are self-explanatory. Numbers 
are decimal if they are followed by a point (.); otherwise, they are 
hexadecimal. 


Figure 6-7 illustrates the Image Synopsis section. 


6.2.8 Link Run Statistics 


The Link Run Statistics section, which appears in all maps, gives 
statistics of the link run that produced the image. The items are 
self-explanatory. 


Figure 6-8 illustrates the Link Run Statistics section. 
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CHAPTER 7 


IMAGE CREATION 


This chapter discusses the allocation of virtual memory and_ the 
different kinds of images that the linker can produce. The concepts 
of program sections, image sections, and clusters are introduced, 
along with a description of the way in which the linker builds the 
final image. 


7.1 PROGRAM SECTIONS 


Program sections are areas of memory that have a name, a length, and a 
series of attributes (detailed in Section 7.5.4) that describe the 
intended or permitted usage of that portion of memory. The program 
section is the vehicle by which a language compiler describes the 
Memory requirements of a particular object module. 


7.2 IMAGE SECTIONS 


Image sections are named collections of pages; each page in an image 
section has the same hardware protection characteristics and the same 
sharing nature. The image sections describe the memory requirements 
of the whole image to the VAX/VMS memory management software. 


The linker creates image sections by collecting program sections that 
have similar (but not necessarily identical) attributes. The manner 
in which program sections are grouped into image sections depends upon 
both the attributes of each program section and the type of image 
being produced (see Section 7.7). 


7.3 CLUSTERS 


Clusters are collections of image sections. Clustering provides a way 
for the designer of an application program to ensure that an image 
section is near, in virtual memory, to the image sections that it 
references and that reference it. Having related image sections near 
each other improves the performance of large application programs. 


An example of an application program that could use clustering is a 
compiler. A compiler usually goes through a number of distinct phases 
during a single compilation run. Each phase of the compiler could be 
made into a separate cluster to improve the compiler's performance. 


Every image consists of at least one cluster. You can specify 
additional clusters in two ways: by object modules or by program 
sections. The CLUSTER= option (see Section 5.3) causes image sections 
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created from the specified object modules to be in the same cluster. 
The COLLECT= option (see Section 5.3) causes image sections created 
from the specified program sections to be in the same cluster. In 
both cases, the image sections are put in the cluster in the order 


described in Section 7.7. 
Note that clusters are relevant only to the linker itself; they do 


not appear as a structure to anything else (such as to the VAX-11 
memory management software). See Section 7.9 for more information. 


7.4 OBJECT MODULE CONTENTS 

Each object module contains several types of records. All object 
modules have header records and an end-of-module record. Some also 
have other kinds of records, depending on the options specified at 
compilation. All object modules also contain the following records 
for each of the program sections: 

@ A global symbol record that includes the program section's 
attributes. (A global symbol record is also used to describe 
each global symbol defined in the module.) 

e A text information and relocation record, containing the 
section's binary data or code and certain commands to the 
linker. 


Appendix C contains a detailed specification of the object language 
accepted by the linker. 


7.5 PROGRAM SECTIONS 

A program section is defined to the linker by the following: 
® A name 
e A size 
e An alignment 


e A series of single-bit attributes expressing whether the 
program section is: 


- Relocatable or absolute 

- Concatenated or overlaid 

- Local to a cluster or global across all clusters 

- Executable or not 

~ Writeable or not 

- Readable or not 

- Position-independent or not 

- Potentially shareable or not 

- Created by a user program or by the linker for internal use 
- Has protected vectors or not 
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7.5.1 Program Section Name 


The program section name is an ASCII character string, 1 through 31 
characters in length. You can use any printable ASCII character in 
the name, but are cautioned against using the dollar sign ($), to 
avoid possible naming conflicts with software supplied by DIGITAL. 


Program sections with the same name but from different modules 
normally must have the same attributes. Any exceptions to this rule 
are noted in the discussions of specific attributes. 


7.5.2 Program Section Size 


The size field of a program section definition record is a 32-bit 
count of the number of bytes that this module contributes to the 
program section. 


7.5.3 Program Section Alignment 


The alignment field describes the address boundary at which the 
module's contribution to the program section will be placed. The 
alignment is expressed as a number from 0 through 9, representing a 
power of 2. The base address of the program section is rounded up to 
a multiple of that power of two. 


In an overlaid program section, all contributing modules must specify 
the same alignment; otherwise, the linker generates a diagnostic 
error. In a concatenated program section, each contributing module 
can specify a different alignment. The total allocation of the 
concatenated program section is aligned on a boundary which is a 
multiple of the highest power of 2 specified by any of the 
contributing modules. 


7.5.4 Program Section Attributes 


The following subsections explain the attributes that a program 
section can have. Section 7.7 describes how the linker considers 
certain significant attributes as it constructs different types of 
images. Section 5.3 describes the PSECT _ATTR option, which allows you 
to change the attributes of a program section. 


7.5.4.1 Relocatability (REL and ABS) - A program section can be 
relocatable or absolute. A relocatable program section is one that 
the linker can position in virtual memory according to the memory 
allocation strategy for the type of image being produced. 


Absolute program sections, on the other hand, are not considered in 
the allocation of virtual memory. They contain no binary data or 
code, and all appear as if they were based at a virtual address of 
zero. Absolute program sections are used primarily to define global 
symbols. 
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7.5.4.2 Concatenated versus Overlaid (CON and OVR) - This attribute 
determines the relationship between the memory allocations when 
several modules contribute program sections with the same name. 


A concatenated program section contribution requires separate address 
space in the image. If two program sections from different modules 
have the same name, the sections will be placed in separate but 
contiguous address spaces. For example, if PSECTA in MODULE1 and 
PSECTA in MODULE2 have the concatenated attribute, the allocation of 
PSECTA from MODULE1 will be followed by the allocation of PSECTA from 
MODULE2. The total size of a concatenated program section is the sum 
of the individual contributions and any padding allowed for the 
individual alignments. 


An overlaid program section contribution, however, can share an 
address space with other program sections that have the same name. 
For example, if PSECTA in MODULE] and PSECTA in MODULE2 each have’ the 
overlaid attribute, both program section contributions will be 
allocated starting at the same base address in the image. The total 
size of an overlaid program section is that of the largest 
contribution. 


Note that any module can initialize the contents of an overlaid 
program section. Because of this, the order in which you specify the 
input modules is important: the contents of an overlaid program 
section are determined by the last contributing module specified. 


BASIC and FORTRAN common areas are the most frequently used overlaid 
program sections. 


7.5.4.3 Scope ~ Local versus Global (LCL and GBL) - The local or 
global attribute is significant for an image that has more than one 
cluster. The attribute determines whether program sections with the 
same name but from modules in different clusters are finally placed in 
separate clusters (LCL attribute) or in the same cluster (GBL 
attribute). The memory of a global program section is allocated in 
the cluster that contains the first contributing module. 


BASIC and FORTRAN common areas are implemented with global program 
sections. 


7.5.4.4 Executability (EXE and NOEXE) - Although the current VAX-11 
hardware does not implement any kind of execute protection, this 
attribute is reserved for possible future implementation. This 
attribute also permits possible future extension of link time error 
detection and of software security protection. 


The current version of the linker takes this attribute into account in 
only two ways: 


e Error-checking on an image start address. The linker issues a 
diagnostic message if a program transfer address is defined in 
a nonexecutable program section. 


e Sorting of program sections into image sections. Executable 
program sections in executable and shareable images are placed 
in image sections separate from program sections that are not 
executable. 
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7.5.4.5 Writeability (WRT and NOWRT) - This attribute determines 
whether the program section contents will be protected against 
modification when the image is executed. If the program attempts to 
modify the contents of a non-writeable program section during 
execution, an access violation occurs. 


For executable and shareable images, writeable and nonwriteable 
program sections are placed in different image sections. For system 
images, this attribute is ignored, since by definition the VAX/VMS 
system is not normally in control of the memory management of a system 
image. 


7.5.4.6 Readability (RD and NORD) - The current version of the linker 
ignores this attribute. It is provided merely to allow the possible 
future implementation of a data security system. 


7.5.4.7 Position Independence (PIC and NOPIC) - This attribute 
identifies whether the content of a program section depends on where 
that program section or something that it refers to is allocated in 
the virtual address space. For example, the following types of 
program sections are position independent: 


e A program section that contains no virtual addresses 


e A program section whose references to virtual memory are _ in 
the form of a displacement from itself, if the targets of the 
references must always be at the same displacement from the 
calls which refer to them 


This attribute applies only to shareable images, which are discussed 
in Chapter 8. 


7.5.4.8 Shareability (SHR and NOSHR) - As its name suggests, this 
attribute is significant only for shareable image memory allocation 
and memory management (see Chapter 8). 


7.5.4.9 User versus Library (USR and LIB) - This attribute is 
reserved for possible future enhancements to the linker. It is 
ignored for the current release but should be set to USR to guarantee 
future compatibility. 


7.5.4.10 Protection (VEC and NOVEC) - The VEC attribute specifies 
that the program section contains privileged change mode vectors. 
Program sections with the VEC attribute are automatically protected in 
shareable images. See the description of privileged shareable images 
in the VAX/VMS Real-Time User's Guide for more information. 





7.6 TYPES OF IMAGES 


The linker creates three types of images: executable, shareable, and 
system. Each type has specific uses. System images differ 
substantially in content and organization from executable images and 
shareable images. The following subsections define each type. 


7-5 
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7.6.1 Executable Images 


An executable image is a program that you can activate by the RUN 


command. The most common use of the linker is to create executable 
images. 


An executable image cannot be linked with other images. However, the 
object modules that make up one executable image can he linked in 
different combinations or with different link options to form 
different executable images. 


7.6.2 Shareable Images 
There are two major reasons for shareable images: 


e To provide a means of sharing a single physical copy of a set 
of procedures and/or data between multiple application 
programs 


e To facilitate the linking of very large applications (say, 
hundreds of modules) in manageable segments 


As with executable images, when the link of a shareable image is 
complete, all symbolic references are resolved and memory is allocated 
to a group of image sections. A description of each image section is 
written to the image header. Unlike an executable image, however, a 
shareable image normally has a symbol table appended to it. 


A shareable image is not directly  runnable. It is intended for 
reprocessing by the linker--that is, to be included in a subsequent 
image. In processing a shareable image, the linker reads the image 
header and generates a separate image cluster from the set of image 
sections it finds. 


After generating the cluster that is the incoming shareable image, the 
linker processes the symbol table appended to the image just as if it 
were an object module. This allows the shareable image to resolve 
symbols (usually routine names) referred to by the modules with which 
it is being linked. These symbols are called universal symbols (see 
Section 2.2.3). 


When you run a program that has been linked with a shareable image, 
the VAX-11 image activator checks to see if the shareable image has 
been installed by the system manager. If it has been installed, the 
image activator sets a pointer that enables the process to use the 
shareable image. Thus, whenever multiple processes request an 
installed shareable image, the operating system makes the same 
physical copy of the shareable image available to each requesting 
process. Shareable images can therefore conserve physical memory at 
run time. If the shareable image has not been installed, the image 
activator creates a private copy of the shareable image. 


Chapter 8 discusses shareable images further. At this point, however, 
note the following information and conventions pertaining to shareable 
images: 


e The default common Run-Time Procedure Library provided with 
the VAX/VMS system is a shareable image. 


@e You cannot link the VAX-11 Symbolic Debugger with a shareable 
image. 
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e You can request that the linker produce a private copy of a 
shareable image in an executable image file. By default, 
however, the linker does not do so, thereby saving disk space. 


e Chapters 4 and 5 describe LINK command qualifiers and _ link 
time options specifically intended for dealing with shareable 
images. See the following: 


/SYSSHR 

qualifiers 
/SHAREABLE 
UNIVERSAL= 

options 
GSMATCH= 


7.6.3 System Images 


A system image is intended for stand-alone operation on the VAX-11 
hardware; that is, it does not run under the control of the VAX/VMS 
operating system. 


The allocation of memory to a system image is much simpler than _ for 
the other two types of images. The linker allocates memory to the 
program sections based on the alphabetical order of the program 
section names. The only other factors that the linker considers are 
program section size, alignment, and the following attributes: 
concatenated or overlaid, and relocatable or absolute. These factors 
are treated as described in Section 7.5. 


The resulting image is a fixed-length record file, each record being a 
512-byte block. A system image has no image header (unless the 
/HEADER qualifier is specified), no debug data, and no symbol tables. 
It has no set format. That is to say, it contains binary data and 
code just as they would appear in memory. 


7.7 GENERATION OF IMAGE SECTIONS 


The linker makes two passes over the input object modules. The first 
pass builds the symbol table and the program section tables. The 
second pass writes the binary contents of the image. Memory 
allocation is performed between the two passes; the linker uses the 
program section table of each cluster and generates an image section 
table for each cluster. 


When the first pass is complete, the linker has determined the sizes 
of all the relocatable program sections by considering specific 
attributes and the alignment, as discussed in Section 7.5. The linker 
has also determined relative addresses of each module's contribution 
to a particular program section. What remains to be done is to. group 
the program sections into image sections, and to position the whole 
image cluster in the virtual address space. 
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Depending on the type of image being produced, the linker establishes 
a mask for the program section attributes that it will consider: 


@ For an executable image, this mask includes only the 
writeability (WRT and NOWRT), executability (EXE and NOEXE), 
and protected vector (VEC and NOVEC) attributes. 


e For a shareable image, this mask includes the writeability, 
executability, position independence (PIC and NOPIC), 
shareability (SHR and NOSHR), and protected vector (VEC. and 
NOVEC) attributes. 


For each possible combination of the significant attributes, the 
linker searches the program section list of a cluster. If the linker 
finds any program section with this combination of attributes, it 
generates an image section. Each program section with matching 
attributes in the image section is assigned an address relative to the 
base of the image section, in alphabetical order by program section 
name. 


All combinations of significant attributes are handled in this way, 
until the complete set of image sections for the particular cluster is 
generated. Table 7-1 lists the order that the linker stores the image 
sections within a cluster. Each line of the table specifies a 
possible combination of significant attributes. The next cluster (if 
there is one) is then treated in the same way. 


At this point in image creation, all image sections have 
cluster-relative base addresses, and all program sections have image 
section-relative addresses. The next step consists of allocating 
virtual address space to the cluster and then relocating all image 
sections and program sections within the cluster. 


The choice of address space for the cluster depends on whether you 
specified an address in the CLUSTER= option, and whether the cluster 
contains a shareable image. It also depends on the order in which you 
specified the clusters. 


7.8 COMPRESSION OF UNINITIALIZED IMAGE SECTIONS 


At the end of its first pass across the object modules, the linker 
Sorts all the program sections into a group of distinct image 
sections. The sorting is determined by program section attributes and 
results in the complete allocation of the user virtual space. 


In its second pass, the linker writes the binary contents of the 
image. During this image initialization, the linker keeps track of 
the program section being initialized and the image section to which 
it has been allocated. The first attempt to initialize part of an 
image section causes the linker to allocate a buffer in its own 
program region to contain the binary contents of the generated image 
section. This allocation is achieved by the expand region system 
service, and it requires that the linker have available a virtually 
contiguous region of its own memory at least as large as the image 
section being initialized. 


After completing the second pass across the object modules, the linker 
scans the list of image sections in an attempt to compress 
uninitialized pages from the image, which is about to be written. The 
linker attempts to perform this compression by creating demand zero 
image sections. The linker scans the image sections and attempts’ to 
compress uninitialized pages when it is creating executable images 
only. 
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Table 7-1 
Order of Image Sections in Clusters 

















Type of Image Image Section PSECT Attributes 

Executable NOWRT NOEXE - 7 NOVEC 
WRT NOEXE ~ = NOVEC 
NOWRT EXE - = NOVEC 
WRT EXE - a NOVEC 
NOWRT NOEXE - - VEC 
WRT NOEXE - = VEC 
NOWRT EXE - = VEC 
WRT EXE - - VEC 

Shareable NOWRT NOEXE SHR NOPIC NOVEC 
WRT NOEXE SHR NOPIC NOVEC 
NOWRT EXE SHR NOPIC NOVEC 
WRT EXE SHR NOPIC NOVEC 
NOWRT NOEXE NOSHR NOPIC NOVEC 
WRT NOEXE NOSHR NOPIC NOVEC 
NOWRT EXE NOSHR NOPIC NOVEC 
WRT EXE NOSHR NOPIC NOVEC 
NOWRT NOEXE SHR PIc NOVEC 
WRT NOEXE SHR PIC NOVEC 
NOWRT EXE SHR PIC NOVEC 
WRT EXE SHR PIC NOVEC 
NOWRT NOEXE NOSHR PIC NOVEC 
WRT NOEXE NOSHR PIC NOVEC 
NOWRT EXE NOSHR PIC NOVEC 
WRT EXE NOSHR PIC NOVEC 
NOWRT NOEXE SHR NOPIC VEC 
WRT NOEXE SHR NOPIC VEC 
NOWRT EXE SHR NOPIC VEC 
WRT EXE SHR NOPIC VEC 
NOWRT NOEXE NOSHR NOPIC VEC 
WRT NOEXE NOSHR NOPIC VEC 
NOWRT EXE NOSHR NOPIC VEC 
WRT EXE NOSHR NOPIC VEC 
NOWRT NOEXE SHR PIC VEC 
WRT NOEXE SHR PIC VEC 
NOWRT EXE SHR PIC VEC 
WRT EXE SHR PIC VEC 
NOWRT NOEXE NOSHR PIC VEC 
WRT NOEXE NOSHR PIC VEC 
NOWRT EXE NOSHR PIC VEC 


WRT EXE NOSHR PIC VEC 





System 7 7 ras 7 = 
(only one image section) 
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If the linker finds an image section that does not have a buffer 
allocated, it considers splitting the section into multiple image 
sections, some demand zero and others copy on reference. To be 
eligible for splitting, the image section must be writeable to the 
user and larger than the minimum compression threshold size (see the 
DZRO_ MIN= option in Chapter 5). If the image section can be split, 
the linker calls a memory management system service, passing it a 
description of the image section buffer and the compression threshold 
value. By calling this service in a loop, the linker finds out which 
segments of the buffer are both larger than the threshold number of 
pages and previously unmodified by the linker. This process’ results 
in the replacement of a single image section by a potentially large 
number of alternating demand zero and copy on reference image 
sections. 


The linker continues the splitting process, scanning the list of image 
sections until it reaches the end or until the total number of image 
sections reaches the limit specified or defaulted for the ISD_MAX= 
option (see Chapter 5). During the entire process, the linker keeps 
track of the size of the image header (where descriptors of the image 
sections will be written) and of the image binary contents. Thus, at 
the end of the scan the linker knows the precise size of the image 
header and the contents, and it can then create the image file. 


When the image file is successfully created, the linker makes another 
scan of the image section descriptor list. During this scan it writes 
the contents of all existing image section buffers to the image file, 
asSigning them virtual block numbers as it does so. Finally, the 
linker writes the image header, starting at virtual block number 1 of 
the image file. 


By default, the linker creates the image with the attribute 
“contiguous best try," which becomes a permanent attribute of the 
image file. However, you can specify the /CONTIGUOUS qualifier to 
force the image file to be created contiguously (see Chapter 4). 


7.9 MECHANICS OF CLUSTERING 


Section 5.3 describes the CLUSTER= and COLLECT= options, which are 
used to define the position, character, and content of clusters. The 
cluster name is merely for convenience in reading the Image Section 
Synopsis of the image map. 


Every image produced by the linker is automatically given a default 
cluster. This cluster contains any object modules not explicitly 
positioned in other clusters. The BASE= option serves to position the 
default cluster in the address space. 


A shareable image is treated as a cluster, If the image is not 
position independent (NOPIC), it has a base address already assigned 
and is treated in the same manner as a user-specified cluster that has 
a base address. 
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The linker allocates virtual address space for clusters in the 
following order: 


e Clusters that have fixed bases (including position-dependent 
shareable images). If any of these clusters overlap, the 
linker displays an error message. 


@ User-specified clusters without fixed bases. These are 
allocated in the order specified. 


e Default cluster (if it contains any modules and does not have 
a fixed base) 


e Position-independent shareable images 


e Run-time library shareable image (if it is included in _ the 
image) 


Clustering is not likely to have any performance advantage for 
applications smaller than 200K bytes, The reason is that each cluster 
contains a group of image sections, and thus the address space is more 
fragmented than it would be without clustering. Fragmentation can 
reduce program performance under certain circumstances. 


CHAPTER 8 


SHAREABLE IMAGES 


This chapter describes in detail the nature and use of shareable 
images. The material in this chapter is more complex than much of the 
earlier material. Therefore, you are presumed to be familiar with the 
earlier chapters of this manual, particularly Chapter 7. 


8.1 SHAREABLE IMAGES: BENEFITS AND USES 


The following subsections expand on the discussion in Section 7.6 of 
the benefits you can obtain from the use of shareable images. These 
subsections also discuss the conceptual nature of shareable images. 


8.1.1 Conserving Physical Memory 


Main physical memory is one of the prime resources that any operating 
system has to control. The installation of shareable images produces 
a set of global sections of memory -- one for each image section built 
in the shareable image. These global sections are the mechanism by 
which sharing is realized, for they can be mapped into the address 
space of many processes. The fact that the same physical pages of a 
global section are mapped into many processes means’ that the 
requirements for physical memory are reduced. 


8.1.2 Conserving Disk Storage Space 


All programs executed under the VAX/VMS system must be disk resident. 
The use of shareable images, however, provides a way of reducing the 
amount of disk space required. 


When a shareable image is linked into an executable image, it is not 
necessary to copy the physical contents of the shareable image. The 
installation of a shareable image causes the location of that image on 
disk to be recorded in the system's global section data base. The 
subsequent running of a program that uses that shareable image causes 
the VAX/VMS memory management software to load the copy from the 
separate shareable image file. Thus, many programs can reside on disk 
and be bound with a particular shareable image, and only one physical 
copy of that shareable image file need exist on disk. 
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8.1.3 Reducing Paging 1/0 


Paging occurs when a process attempts to access a virtual address 
which is not in the process working set. When the fault occurs, the 
page either is in a disk file (in which case paging I/O is required) 
or is already in physical memory. One of the reasons a page can be 
resident when a fault occurs is that it is a shared page, already 
faulted by some other process which is sharing it. In this case, no 
I/O operation is required before mapping the page into the working 
sets of subsequent processes. Thus, if many processes are using a 
shareable image, it is very likely that its pages are already 
physically resident. 


8.1.4 Using Shared Memory-Resident Data Bases 


There are many applications, particularly in data acquisition and 
control systems, in which response times are so critical that control 
variables and data readings must remain in main memory. Frequently, 
IMany programs muSt make use of this data, 


Shareable images help to simplify the implementation of such 
applications. The shared data base may be a named FORTRAN common area 
built into a shareable image. The shareable image may also include 
routines to synchronize access to such data. When programs of the 
application bind with the shareable image, they have easy access. to 
the data (and routines) at the FORTRAN level. 


It is possible, moreover, for such data bases to contain initial 
values, and for the most recent values to be written back to disk on 
system shutdown or at regular intervals. Recording the values at 
regular intervals makes it possible for a system restart to use the 
most recent values of the variables of an online process. 


8.1.5 Making Software Updates Compatible 


A major problem in maintaining a large software installation is how to 
incorporate a new version of a piece of software in all programs that 
use it. Packaging software facilities as shareable images can help 
alleviate the problem. 


By carefully organizing a shareable image and by using 
position-independent coding techniques, you can make significant 
changes and enhancements to the content of the shareable image and yet 
eliminate the need to relink all the images bound with it. 


8.2 WRITING SOURCE PROGRAMS FOR SHAREABLE IMAGES 


In order to obtain all the benefits of a shareable image, you must 
observe certain conventions in the source programs used to create it. 
This section describes these conventions. 
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8.2.1 Shareable and Nonshareable Data 


The sharing of routines between two or more processes must address the 
issue of whether each process has access to data that one or more 
other processes are using. Sometimes this sharing is a requirement, 
as in the case of industrial data acquisition applications. However, 
if a piece of data used by a routine is, for instance, a loop counter, 
each process must have a separate counter, or the routine cannot be 
shared simultaneously. It is for this situation that the shareable 
(SHR) attribute of program sections was introduced. Users familiar 
with this situation recognize it as part of the problem referred to as 
reentrancy. 


As was mentioned in Chapter 7, the linker allocates program sections 
with the SHR attribute in image sections separate from program 
sections with the NOSHR attribute. The image activator also treats 
image sections containing SHR program sections differently from image 
sections containing NOSHR program sections. The linker indicates this 
difference by an image section attribute called "copy on reference" in 
the case of writeable NOSHR program sections. (If the program section 
is not writeable, all processes can use the same copy regardless of 
SHR/NOSHR, since no form of data privacy or security is currently 
implemented.) 


Thus, a copy on reference image section is one whose initial contents 
are established from the copy contained in the shareable image file, 
but which from then on during program execution is treated just like a 
user private image section. For each user, completely separate 
physical copies are produced for the copy on reference image sections 
contained in shareable images, and the system paging file is used to 
contain the pages of such sections when they are removed from the 
working set. 


On the other hand, if an image section is not copy on reference, each 
user has access to the same physical copy of its pages. In addition, 
when a page of such an image is removed from all user working sets, it 
is eventually written back into the shareable image file on disk. 
This last aspect makes it possible to rerun such applications as data 
acquisition or transaction processing with the most recent values of 
shareable, modifiable data. 


Note that the cooperating user programs in applications like these are 
responsible for synchronizing access to such data. Note further that 
Should it be necessary to revert to the initial values of the data, 
you must have made a separate copy before running the application the 
first time. 


The FORTRAN example in Section 8.4.2 shows both kinds of data: 
variables generated by the compiler and the program are in copy on 
reference image sections, whereas the common areas are in shared data 
regions. 


8.2.2 Position Independence 


A position independent piece of code will execute correctly no matter 
where it is placed in the virtual address space after it is linked. 
That is, it can execute at an address different from the one at which 
the linker placed it. This section deals with position independence 
only as it concerns shareable images. 
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A shareable image is position independent if all of the following 
conditions are true: 


The only addresses that appear in the image are known to be 
fixed in the virtual address space (for example, the system 
service vectors of VAX/VMS). Note that if you specify a 
relocatable address in a shareable image, the linker will 
maintain the position independence by deferred relocation of 
the address. 


All instruction stream references to such addresses use 
absolute addressing mode (autoincrement deferred off the PC). 


All data references to such fixed addresses contain the 
complete virtual address. 


All references to any other location are relative to some base 
that is added to the address computation at execution time. 
For example, in the instruction stream, PC relative (or 
displacement from the PC) addressing mode would be used. 


There is no possibility that, after linking, the relationship 
between the target of a reference and the base to which it was 
made relative can be changed. 


The current version of the linker is unable to verify that all the 
above conditions have been met. Therefore, the following strategy has 
been adopted: 


If any base address has been specified, the resultant 
shareable image is not position independent. 


The state of the position-independence attribute of the 
program sections is left to the user, and is considered only 
in gathering program sections into image sections. That is, 
the linker simply places PIC program sections in image 
sections separate from NOPIC program sections. 


With assistance from the compiler or assembler, the linker 
produces position-independent instruction stream references. 
(Refer to the discussion of the general addressing mode in the 
VAX-11 MACRO Language Reference Manual.) Basically, this means 
that the linker will choose 








the addressing mode (if so 
directed) based on the relocatability of the target of the 
reference, 


With assistance from the compiler or assembler, the linker 
produces position-independent address data by means of 
deferred relocation. 


A shareable image that is not position independent is placed 
at its link-time base address when it is subsequently bound 
into a user image. 


A shareable image that is position independent is allocated 
after user-defined clusters when it is subsequently bound into 
a user image. 


Shareable images that are not position independent are 
considered first by the linker. 


Deferred relocation is the relocation of address data that is deferred 


until 


the executable image is linked from the shareable image. The 


linker uses deferred relocation when an image section contains a 
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-ADDRESS directive (VAX-1l1 MACRO) specifying a relocatable address. 
The linker marks the image section as COPY ALWAYS. When an executable 
image is linked from the shareable image, the linker copies the image 
section into the executable image and then calculates the correct 
address. 


Note that to retain the benefits of a shareable image, .ADDRESS with a 
relocatable address should only occur in an image section that 
contains nonshareable data. These are the image sections that have 
the NOSHR and WRT attributes. 


If shareable images are to be most useful among many processes, they 
should be position independent. The VAX-11 instruction set and 
addressing modes lend themselves’ to convenient generation of 
position-independent code. All the code generated by the VAX-ll 
FORTRAN and VAX-11 BASIC compilers is position independent. 


8.2.3 Transfer Vectors 


In its simplest form, a transfer vector is a labeled virtual memory 
location that contains an address of, or a displacement to, a second 
location in virtual memory. The second location is the start of the 
instruction stream of interest. In the use of shareable images under 
VAX/VMS, transfer vectors are normally displacements rather’ than 
virtual addresses, for reasons of position independence. 


There are two main reasons for transfer vectors in shareable images: 


@e They make it easy to modify and enhance the contents of the 
shareable image. 


e They allow you to avoid relinking other programs that are 
bound to the shareable image. 


In Figure 8-1, the two routines A and B are bound into aé_= shareable 
image, which is then bound into a user program. No transfer vectors 
are used. The user program calls both A and B. Thus, the user 
program contains a representation of the addresses of both A and B. 







User Program 


Routine A 


Routine A 

is expanded 

New position Routine B 
of Routine B 

for larger A 


New Expansion Area Expansion Area 


Shareable Image 


Figure 8-1 No Transfer Vectors 
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Using the example in Figure 8-1, assume that it becomes necessary to 
add more code to routine A. When the shareable image is relinked, 
routine A will have the same address but because routine A_ has 
increased in size, routine B must be given a "higher" 
address -- higher by the amount of code added to A. If the user 
program is not relinked, it can successfully call A, since its address 
has not changed. However, the call to B would result in a transfer of 
control to the old address of B (which is now somewhere in the 
enlarged routine A), and the desired result would not occur. Note 
that if the total size of the shareable image is larger, the user 
program must be relinked. (See Section 8.2.4). 


In Figure 8-2, the same routines are built into a shareable image, but 
this time with transfer vectors at the beginning. 
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Figure 8-2 Transfer Vectors 


In Figure 8-2, if routine A is expanded and the shareable image is 
relinked, the contents of the vector will change with no adverse 
affect on the user program. This is true so long as the user program 
calls the appropriate vector and the vector addresses do not change. 


The use of transfer vectors also allows you to add new routines to a 
shareable image without needing to relink programs that use existing 
routines. If a third routine (C) were added, it would be desirable 
not to have to relink a user program that used only A and B. Without 
a vector, you would need to link the three routines in the address 
sequence A,B,C; -- otherwise A or B could be in a different place and 
all user programs linked to the shareable image would need to be 
relinked. If you use a transfer vector, however, you can allocate a 
new vector location to C (after those for A and B). You can then link 
the three routines in any order. 


Although you cannot create transfer vectors with FORTRAN, you can do 
so easily with VAX-11 MACRO. However, before you can create transfer 
vectors, you must define or permit the compiler to define entry 
points. With FORTRAN, the definition of entry points is done 
automatically, but with VAX-11 MACRO, you must explicitly define them. 
As an illustration, assume in Figure 8-2 that routines A and B are 
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written in FORTRAN. In this case, the two global symbols A and B are 
defined as entry points, and the definitions given to the linker 
include a description of the registers to be saved with the call 
instruction, (You can achieve the same effect with the MACRO 
directive .ENTRY. See the VAX-11 MACRO Language Reference Manual.) 


To create the transfer vector, you must use the VAX-11 MACRO assembler 
language. Consider the following fragment of MACRO code: 


» TRANSFER A ;Begin transfer vector to A 
«MASK A ;Store register save mask 
BRW A+2 ;BR to routine, beyond the 


; register save mask 


As the example suggests, register save masks (required at the target 
of a CALL instruction) occupy two bytes of memory. Thus, since it is 
the vector that you actually call, the register save mask is stored in 
the vector. The .MASK directive in the above example allocates the 
two bytes and directs the linker to (1) find the register save mask 
accompanying symbol A, and (2) write the word as the first two bytes 
of the vector. This mask is followed by a branch instruction that 
transfers control to routine A, at the instruction beyond the entry 
mask. (This example assumes that A is within 32K bytes of the vector; 
otherwise a JMP instruction would be required.) 


The .TRANSFER directive has two purposes: 


e It is an implicit universal declaration of symbol A if you are 
building a shareable image. 


@ It causes the linker to assign the universal symbol A_ the 
address of the vector, rather than the address of the routine 
within the image. This occurs after all uses of A within’ the 
shareable image have been given the value within the image. 


Thus, all entry points of a shareable image are universal when 
vectored in this way. The user program outside the shareable image 
can call the routine A in the same way as it would an ordinary object 
module. 


8.2.4 Rules for Creating Upwardly Compatible Shareable Images 


To be able to make changes to shareable images and not have to_ relink 
users of that shareable image, you must observe the following rules: 


e Transfer vectors must not be rearranged or removed. 


e The new shareable image must have exactly the same number of 
image sections. 


e The shareable image must not be larger than it originally was 
unless the shareable image is the cluster with the largest 
virtual address in the image (this position is usually 
reserved for the run-time library). 


While a shareable image is being developed, it is useful to reserve 
expansion space to allow the image to grow. If you exceed the 
expansion space, you must relink all executable images that are linked 
with the shareable image. Because there is a substantial overhead for 
increasing the size of a shareable image (one entry in the system's 
Global Page Table per shareable page), you should reduce the expansion 
area when the shareable image is no longer being developed. 


8-7 


SHAREABLE IMAGES 


8.3 LINK COMMAND AND PERTINENT OPTIONS 


The LINK command for creating a shareable image is similar to that for 
any other type of image, except that you must use the 
/SHAREABLE[=file-spec] qualifier, which is described in Chapter 4. 


The UNIVERSAL=, GSMATCH=, and PROTECT= options and the /PROTECT 
qualifier are provided specifically to control characteristics of 
shareable images. Chapter 5 describes the syntax of these options. 
Sections 8.3.1, 8.3.2, and 8.3.3 describe their purpose. 


8.3.1 UNIVERSAL= Option 


Universal symbols are the global symbols of a shareable image which 
are of use to the programs that subsequently link with the shareable 
image. It is possible for none or all of the global symbols of a 
shareable image to be universal symbols. Typically, however, a very 
small set of the global symbols of the image are universal because few 
of them are of use outside the shareable image. Universal symbols are 
the only symbols written to the symbol table of a shareable image. 


Most programming languages provide no way of characterizing a symbol 
as universal. (VAX-11 MACRO, however, has a declaration for creating 
transfer vectors. See Section 8.2.3.) Thus, to tell the linker which 
symbols are to be universal, the option UNIVERSAL= is provided. 


Normally, all the entry points (routine names) provided in a shareable 
image are universal symbols. Sometimes, however, other constants are 
of interest to users of the facility, and these can also be declared 
as universal symbols. Section 8.4.1 contains an example showing the 
declaration of several such constants in the Cross Reference Facility 
as universal symbols. 


8.3.2 GSMATCH= Option 


When a shareable image is bound into a user executable image, its 
image sections are promoted to global sections. (The VAX/VMS system 
promotes image sections to global sections when a shareable image is 
installed.) When an executable image is run, the image activator 
checks to see if the shareable image that the executable image was 
linked with matches the current one. The image activator compares the 
values specified in the GSMATCH= option when the shareable images were 
linked (see Section 5.3). 


The GSMATCH= option sets the matching requirements for versions of the 
shareable image and causes a two-part identification field to be 
associated with the global section name. During the search for a 
global section at image activation time, the global section name and 
the major part of the identification must match exactly. The behavior 
of the comparison with the minor part of the identification is 
determined by the keyword specified in the GSMATCH= option. The 
keyword can be: 


e EQUAL -- the minor identifications must match, 
e LEQUAL -- the minor identification of the global section in 


the user image must be less’ than or equal to that in the 
global data base. 
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@ NEVER -- even if both parts of the identification match 
exactly, the image activator rejects the shareable image. The 
purpose of NEVER is to specify that the linker should always 


produce a private copy of this shareable image in each 
executable image file. 


e ALWAYS -- the image activator only checks to see that the 
global section names are the same and ignores both parts of 
the identification. 


The GSMATCH= option is provided to set these parameters when the 
shareable image is being linked. See Section 8.5 for mre information 
on the effects of these parameters. 


8.3.3 PROTECT = Option and /PROTECT Qualifier 


The PROTECT= option and the /PROTECT command qualifier are used _ to 
create privileged shareable images. A privileged shareable image can 
execute change mode to kernel and execute change mode to executive 
instructions even when it is linked with a nonprivileged executable 
image. A privileged shareable image allows executable images to call 
user~written procedures with enhanced privileges in the same way that 
they call system services. 


The PROTECT= option protects specified image clusters, and_ the 
“PROTECT command qualifier protects the entire shareable image. 
Another way to protect code is by using the VEC program section 
attribute which protects an individual program section. 


There are three effects of protecting a segment of a shareable image: 
e The shareable image is made a privileged shareable image. 


e Within the protected segment, the change mode instructions are 


allowed even when the process does not have the necessary 
privilege. 


@ Code executing in user mode cannot write in protected areas. 


When creating a privileged shareable image, you should protect’ the 
clusters that require privilege, and not protect the clusters to which 
code executing in user mode needs write access. The /PROTECT command 
qualifier should only be used when the entire shareable image needs to 
be protected. The VEC program section attribute should only be used 
for the program section that contains the change mode dispatch 
vectors. See the VAX/VMS Real-Time User's Guide for more information 
on privileged shareable images. 


8.4 EXAMPLES OF SHAREABLE IMAGES 


The following sections contain examples of shareable images. 


8.4.1 Example of Transfer Vector and Universal Symbols 


Figure 8-3 is a listing of the source code for the module that is the 
transfer vector for the Cross Reference Facility. Figure 8-4 shows 
the LINK command and options files used to create the shareable image 
CRFSHR on the logical device EXECS:. Figure 8-5 shows the map that 
resulted from this link operation. 
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Note that of the 26 global symbols in the image, only 17 are of 
interest outside the image -- 8 vectored entry points and 9 constants. 
Note also that the transfer vector is placed in its own cluster to 
ensure that it is allocated at the low-addressed end of the address 
space. (As you can see from the example, explicitly defined clusters 
are allocated first in the address space.) 


The values of the transfer vector symbols retain the values of the 


routine addresses. (See the listing of the relocatable universal 
symbols in the map in Figure 8-5.) 
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Image header virtual block limites 
Image binary virtue) block limitsas 
Image name and identification: 
Number of filess 

Number of modules? 

Number of program seetions! 

Number of global symbols? 

Number of image sections? 

Image type: 

Map formats: 

Estimated map lengths 


Performance Indicators 


20-FEB=1982 17956 


Poavecaseceeseesaess 


i Image Synopeis { 


Pueavacevesveuurrat 


O8808282 G2BBBDFF BeeGeCae (3272. bytes, 6. pages) 


a, pages 
i. 1, 


2e Te 
CRFSHR ,OLSs 

4, 

8. 

9e 

16. 

4, 


PIC, SHAREABLE, Global seetion mateh = "LESS/EQUAL", G.S, 


1, bloek) 


6, bloeks) 


FULL im file ",08Bd5 (CRF,LIS]CRFSHR,MAP?1" 


29, blocks 


foesaeceneesnresanecaasat 


} Link Rum Statistics i 


Fveasencuseseeessaraest 


Page Faults 


Command processingt ag 
Pass 13 1a9 
Allocation/Relocationt 15 
Pass 2! 23 
Map data efter object module synopsis$ 29 
Symbol] teble output: 5 
Tote! run values? 221 


CPU Time 

00:90:08,17 
62200200,82 
298:20300,97 
@6230302,29 
00200200,21 
06340:92,04 
02209301,68 


Elapsed Time 
seeeuueeeenn 
68:90300,65 
98:00185,80 
20200300,68 
92209302,26 
@0:369100,87 
06:09306,28 
98:20:09,866 


Using e working set limited to 508 sages and 78 peges of data storage Cexcluding image) 


Total number object records read (both passes): 369 
of which 173 were in libraries and 26 were DEBUG date records containing 927 bytes 


Number of modules extracted explicitly 


z2 


with S extracted to resolve undefined symbols 


2 library searches were for symbols not in the library searched 


A total of 4 global symbo! table records was written 


/SHAREBEXES :CRFSHR/MAPaMAPS I CRESHR/FULL SYSSINPUT/OPTIONS 


Figure 8-5 (Cont.) 


Transfer Vector Example Map 
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SHAREABLE IMAGES 


8.4.2 Example of FORTRAN Shared COMMON 


This section contains an example of FORTRAN shared COMMON. The 
FORTRAN subroutine SHRSUB is a_e shareable image that contains two 
COMMON areas. One is a shared or global COMMON area (GLOBAL COMMON). 
This is a data area that is shared by all executable images linked 
with the shareable image. The other is a nonsharéd COMMON area 
(LOCAL COMMON) ; each executable image has its own copy of 
LOCAL COMMON. The program section attributes control whether a COMMON 
area is shared or not. Note the attributes of such program section —- 
in particular, GBL, OVR, and SHR. 


e The GBL attribute causes the program section to be recorded in 
the symbol table of the shareable image for later use by an 
executable image. The FORTRAN compiler sets the GBL attribute 
for all COMMON areas. 


e@ The OVR attribute ensures that all modules contributing to the 
program section start at the same address space. The FORTRAN 
compiler sets the OVR attribute for all COMMON areas. 


e The SHR attribute specifies that only one copy of the COMMON 
area is to appear in physical memory. The FORTRAN compiler 
sets the SHR attribute for all COMMON areas. Note that a 
PSECT_ATTR option in an options file changes the program 
section attribute of LOCAL COMMON to NOSHR. 


Figure 8-6 shows the listing of the FORTRAN subprogram SHRSUB_ that 
defines GLOBAL COMMON and LOCAL COMMON; Figure 8-7 shows the LINK 
command to create the shareable image; and Figure 8-8 shows’ the 
resulting map. Figure 8-9 shows the listing of a FORTRAN program MAIN 
that calls SHRSUB; Figure 8-10 shows the LINK command for MAIN; and 
Figure 8-11 shows the resulting map. 


1¢-8 


Semere1960 18108153 
SeMerei98a 17359801 


Gea} SUBROUTINE SHRSUB 
ia 
c LOCAL COMMON will be private pereimage common 
c GLOBAL, COMMON will be @ shareable common 
c 
e282 COMMON /LOCAL, COMMONS Je J1(511) 
3603 COMMON /GLOBAL COMMONS K-K1(0511) 
@eea TYPE w,° J i im the COPY*ON@REF common, 
{ K de ¢m a shereable common’ 
6aes TYPE *,° Entering @ zero will leave the variable unchanged® 
2006 18 TYPE *,° ° 
2007 TYPE #,° Previous values: J 8 %sJe% KB °oK 
6008 IF (M ,NE, @) J EM 
6009 IF (N ,NE, @} K&N 
8010 TYPE #,° Current veluest J © %,J,° Ke °,K 
Bais TYPE *,° Enter new values for JsK* 
6012 ACCEPT *,M,N 
8813 TF CCM ,EG,. 3) .AND. (N ,EG, BJ) RETURN 
e014 GOTO 18 
6015 END 


PROGRAM SECTIONS 


Name Bytes Attributes 
@ $CODE 316 PIC CON REL LCL SHR EXE 
1 SPDATA 191 PIC CON REL LCL SHR NOEXE 
2 SLOCAL 72 PTC CON REL LCL NOSHR NOEXE 
3 LOCAL COMMON 2248 PIC OVR REL GBL SHR NOEXE 
4 GLOBAL COMMON 2048 PIC OVR REL GBL SHR NOEXE 


ENTRY POINTS 


VAXe1) FORTRAN 11,95036 


aDBB2s (GOLOMAN] SHRSUB,FOR)S 


RD NOWRT LONG 
RD NOWRT LONG 
RD WRT LONG 
RD WRT LONG 
RD WRT LONG 


Address Type Name 
6-98800008 SHRSUB 
VARTABLES 
Address Type Neme Address Type Name Address Type Neme Address 
Seoeaaaeun Ted J 4egpgeeeee Ind K 2-geeeeag8 In4 m 2028009004 
ARRAYS 
Address Type Neme Bytes Dimensions 
3eaoeeeou4 Ind Jt 2044 (511) 
4=@0000004 [ed Ki 2ea4 (811) 


Figure 


8-6 Listing of 


FORTRAN Shared COMMON Subprogram 


Type Neme 


Ts4 NN 


SAOVWWI a IGVauvHsS 
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SHRSUB SeMarci9aa 18:90153 VAXe41 FORTRAN 11,98036 Page 2 
SeMerei988 17659181 .DBB821 [SOLOMAN) SHRSUB,FOR)S 


LABELS 
Address Label 


1°OOGOUO3F 128 
Total Spece Allocated # 4675 Bytes 


COMMAND QUALIFIERS 
FORTRAN /LIST SHRSUB 
/CHEC Kae (NOBOUNDS, OVERFLOW) 


/OEBUG2(NOSYMBOLS, TRACEBACK) 
4F77) /MOGAFLOATING /I4 OPTIMIZE /WARNINGS /NOD LINES /NOMACHINE,CODE /CONTINUATIONS@19 


COMPILATION STATISTICS 


Run Times 1,83 seconds 
Elapsed Times 8,26 seconds 
Pace Faultes 342 

Dynamite Memory? 37 pages 


Figure 8-6 (Cont.)Listing of FORTRAN Shared COMMON Subprogram 
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S$ LINK /SHARESSHRSUB /MAPSSHRSUB /FULL SHRSUB, SYSSINPUTS/OPTIONS 


i 


1 Options input for SHRSUB shareable image 


t 


PSECTSLCCAL, COMMON, NOSHR 
COLLECT=LOCAL CLUSTER,LOCAL, COMMON 
UNI VERSAL=SHRSUS 


Figure 8-7 


LINK Command for FORTRAN Shared COMMON Subprogram 


SGDVWI dTEaVaudVHS 


SHRSUB 


Module Name Ident 
SHRSUB a1 

OTSSLINKAGE 19003 
VMSRTL eEXES! 


wOBB2: (GCLDMAN] SHRSUB,EXEs 4 


. 
= Ses dedi 
LOCAL CLUSTER 4 4 
DEFAULT CLUSTER 3 i 
3 4 
3 1 
4 1 
VMSRTL 3 11 
3 193 
4 4 


22=FEB"198G 14:26 


-weeee ss see eseweserewesee + 


{ Onject Module Synocsis $ 


+e vaasseeevsenaaeroeunvasasy 


File 


Bytes 
4665S ,UBB2: [GOLDMAN] SHRSUS,0B8J;1 

3 sVRaASS (SYSLIB) STARLET. OLB831 

“4 ,ORAS: (SYSLIB] VMSRTL,EXE31 


Creation Date 
2e=Febeil98e@ 14:26 
19=FEB@9198A 21:57 
20°FEB-198W 18355 


22eFERa=198% 14326 


suvessasteousvesecaseswerest} 


1 Image Section Synopsis ! 


Peaster seeeevesessesssenwt 


LINKER V62,42 


Creator 


VaXel!l FORTRAN T1,95"36 


VaAXell Macro V@2,41 


LINK=32 V02,39 


LINKER vd2,4@ 


Base Addr Disk VBN PFC Protection ana Paging Global Sec, Name Metch 
wbeed2re 2 @ READ WRITE COPY ON REF 

SAGPRARL- 6 @ READ ONLY 

avevecer 7 @ READ WRITE 

apguldeu 11 @ READ ONLY 

C8GF1lo8N 12 @ READ wRITE copy Always 

2008180% a 1 READ ONLY VMSRTLOal LESS/EQUAL 
AQUC2E OE a @ READ ONLY VASRTL e282 LESS/EQUAL 
eaeleves ) @ READ WRITE COPY ON REF VMSRTL 823 LESS/EQUAL 

Figure 8-8 Map of FORTRAN Shared COMMON Subprogram 
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Minerid 


2008 
2088 
2008 


{ 


2 
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#9BB2: (GOLDMAN) SHRSUB, EXE; 1 


Peect Name 
LOCAL, COMMON 
SPDATA 

» BLANK , 
GLOBAL, COMMON 
SCODE 


aOTSSCODE 


SLOCAL 


Medule Name 


SHRSUB 


SHRSUB 


OTSSLINKAGE 


SHRSUB 


SHRSUB 


OTSSLINKAGE 


SHRSUB 


26998288 
bedes20e 


BaaaeAan 
BABBGAGe 


@0880486 
BAGRBAGe 


aagaacae 
agasecea 


aeeai4sae 
88ba1 488 


20001534 
20001534 


a4041630 
BUdd1 OHH 


Figure 8-8 (Cont.) 


22-FEB~1988 14426 


sFesresovenvsesssessesreeesss 


i Program Section Synopsis 3 


Poevevaenecequsersusesaousseoety 


End 


OBSQR9FF 
BOBOB9FF 


@AQQ0ABE 
GBQBOABE 


aanagaas 
eageeaca 


OGCBLSFF 
GOBRISFF 


60081534 
90021531 


ACBG1S36 
223001536 


CaAA1647 
20081647 


Length 


@2aeeBF 
@0880GBF 


88088808 
asaeeaed 


298800800 
80986800 


eaaeai3ze 
20000132 


@2828803 
g00a0003 


eaeaaess 
@G0a0a48 


20a8,) 
2048,) 


191.) 
191.) 


@.) 
8.) 


2048,) 
2046,) 


396.) 
306.) 


3.) 
3.) 


72.) 
T2e) 


Alton 


LONG 
LONG 


LONG 
LONG 


BYTE 
BYTE 


LONG 
LONG 


LONG 
LONG 


LONG 
LONG 


LONG 
LONG 


aa vn ft 


fr nt ww Nt 


LINKER Vg2,48 


Attributes 


PIC, USR,CON,RELs LCL 


PIC, USR,OVR, REL, GBL» 


PICeUSReCONSREL, LCL, 


PIC, USReCON,REL» LCL ye 


Map of FORTRAN Shared COMMON Subprogram 


PIC, USR, OVR, REL, GBL» NOSHR, NOEXE, 


SHR,NOEXE, 


NOPIC,/USR,CON,RELe LCL se NOSHR, 


EXE, 


SHR, NOEXE, 


SHR; 


SHR, 


EXE, 


EXE, 


PIC, USR,CONpREL- LCL» NOSHR, NOEXE, 


Page 3 


RO, WRT,NOVEC 
RD, NOWRT, NOVEC 
RD, WRT,NOVEC 
RO, WRT,NOVEC 
RD, NOWRT,NOVEC 
ROsNOWRT,NOVEC 


RD, WRT, NOVEC 


SGOWWI aTaWadVHSs 
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a0BB2: [GOLDMAN] SHRSUB,EXE31 22=FEB=1988 142326 


Peweanmeoaeansencesat 


i Symbols By Name { 


pueunaseeeanansanent 


LINKER VG2,48 


Symbo! Value Sympol Value Symbol Velue 
eu gnen eseue suweuw saase eanueenrs senee 
BASSSBLNK LINE @g0023Ag=RU BASSINSTR OVAS2GBE-RU BASSSCRATCH @AG82308eRU 
BASSSCB_GET OBG02380"RU BASSIN DR AA@WA2LFEeRU BASSSTATUS 828023388RU 
BASS3CB,POP O@8082370eRU BASSIN FR ABSG21EBRU BASSSTRD @ege2ecseRy 


aDBB2Z: [GOLDMAN] SHRSUB,EXE)1 


22=-FE8=1988 14326 


LINKER V@2.48 


Prevess ce vvesesanesn>} 


i Symbols By Value j 


Pressssaevvssesasere> 


Velue SymbolSees 
eucee sueaneensae 
80001400 RU=SHRSUB 
86001534 ReBASSLINKAGE ReFORSLINKAGE ReOTSSLINKAGE 
89001800 RU@FORSCLOSE 
e s 
e a 
. ° 


Key for special characters above? 
Perens ececenocoaaansaaust 
ti *«® © Undefined i 
1U © Universal i 
UR © Relocetable | 
1 WK © Week i 
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Figure 8-8 (Cont.) Map of FORTRAN Shared COMMON Subprogram 


Symbol! 
euauue 
FORSSCB,PUSH 
FORSSCB,LRET 


FORSSERRSNS, SAV 


Page 4 


Value 
seeeag 
GSSGLESSHRY 
BaCGTELSen0 
aea1E2b-R0 
e 
e 
s 
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2DBB2: (GOLDMAN) SHRSUB,EXEs1 22-FEB=1989 14326 LINKER Va2,48 Page 45 


suraeevessseceseensy 


i Image Synopsis i 


Pesseuenecncaeasen+ 


Virtual memory allocated: BAUAB2GS BABLATFF FAALBOHH (112128, bytes, 219, pages) 


Stack size: G, pages 

Image header virtual block limits: 1. 1, ¢ 1. block) 

Image binary virtual block limits: 2. 12. ¢ 11, blocks) 

Image mame and identification: SHRSUS .06J; 

Number of files! 3. 

Number of modules: 3. 

Number of crogram sections: 9. 

Number af glohal symbols: 242. 

Numper of image sections: 9. 

Image type: PIC, SHAREABLE. Global section match = "EQUAL", GS. Ident, Majora2du, Ninors8260915 
Map formats FULL in file “,CBB2: [GOLDMAN] SHRSUB,MAP31" 
Estimated map lengths 55, rlocks 


tame wevennwewaseeenaens 


i Link Run Statistics 1 


+ weweesaevececenaeseeeacent 


Le-8 


Performance Indicators Page Faults CPU Time Elapsed Time 
Commano processing: 42 eercasev, a6 @3:e0200,78 
Pass 1! 182 AAseR2aP,71 on768282.35 
Allocation/Relocatioan: 122 BAGG? 92,26 G64228204,91 
Pass 2: 7a GO2A8380,23 Bvuesdsel.4i 
Fao data after object moaule synopsis! 159 @42e@03a1,84 2G208303,64 
Symbo] table output: 2a O3299304,13 94299305,83 

Total run values: S75 @4240383,23 Gas 4049.92 


Using a working set limited to 268 mages and 51 pages of data storage (excluding image) 


Total number object records read (ocoth passes)? 75 
of which 16 were in libraries anc & were CEFIIG data records containing 149 bytes 


Number of modules extracted exolicitly 


= 34 


with 1 extracted to resolve undefined symrols 


@B library searches were for symbols not in the library searched 


A total of 24 global symbol tanle records was written 


ASHARESSHRKSUB/MAPSSHRSUB/FULL SHRSUG,SYSSINPUTS/0PTIONS 


Figure 8-8 (Cont.) 
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@aa1 PRQ 
@2ee CoM 
@8a3 com 
8804 TyP 
8005 Cal 


G86 TyP 
0807 STO 
aaa8 END 


PROGRAM SECTIONS 
Name 


SCODE 
SPDATA 
SLOCAL 
LOCAL COMMON 
GLOBAL, COMMON 


fWNe 9 


ENTRY POIATS 
Address Type 


G@e@eeoveae 


VARIABLES 
Address Type 


3=09480002 wd 


ARRAYS 
Address Type 


3-AGasURR4 Ixd 
4eBQ0080B4 Ted 


e2-Feb=1980 14326258 
29°Novel979 15824828 


GRAM MAIN 
MON /LOCAL COMMONS J,J1(511) 
MON /GLOBAL COMMONS K,Ki(512) 


E *,° This program tests COPYsONeREF commone’ 
L SmRSUB 

E *,° Finel veluess J = "sJe” 
P "Common test complete’ 


K @ °,K 


Bytes Attributes 
115 PIC CON REL LCL SHR EXE RD NO 
BS PIc CON REL LCL SHR NOEXE RDB NO 


32 PIC CON REL LCL NOSHR NOEXE PD 
2vus PIC OVR REL GBL SHR NOEXE RO 
2¢5e2 PIC QOVR REL GBL SHR NOEXE RD 


Name 

MAIN 

Name Address Type Name 
J 4eNRBDdaA Ted K 
Name Bytes Dimensions 
Ji 2ee44 (511) 

Ki 2248 (S12) 


Figure 8-9 


WRT 
WRT 
WRT 
WRT 
WRT 


VAX@$$ FORTRAN T1,.95=36 
aDBB2s (GOLDMAN) MAIN, FOR? 1 


LONG 
LONG 
LONG 
LONG 
LONG 


Listing of FORTRAN Program Using Shared COMMON 


Page 1 


SUDVAI FIEVauVves 


6c-8 


FUNCTIONS AND SU@ROUTINES REFERENCED 
SHRSUB 


Total Space Allocated = 4332 Bytes 


MAIN 22-Feb-1982 14326158 VAXet1 FORTRAN T1,95936 
29=Novel979 15824328 20BB22 [GOLDMAN] MAIN, FOR} 1 


COMMAND QUALIFIERS 
FORTRAN /LIST MAIN 
/CHECK=(NOBOUNDS, OVERFLOW) 


/DEBUGS (NOS YMBOLS, TRACESACK) 
JF77  sNOGLFLOATING 414 OPTIMIZE /WARNINGS /NOO,LINES /NOMACHINE, CODE /CONTINUATIONS=19 


COMPILATION STATISTICS 


Run Times @.59 seconds 
Elapsed Times 3,42 seconds 
Page Faults: 316 

Dynamic Memory?! 36 pages 


Figure 8-9 (Cont.) Listing of FORTRAN Program Using Shared COMMON 
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SHDWWI FIGVaUVHS 


0e-8 


$ 
a 


t 


LINK /EXESMAIN /MAPSMAIN /FULL MAIN, SYSSINPUTE/OPTIONS 


Options input to link main program 


SHRSUB/SHARE 
PSECTSLOCAL COMMON, NOSHR 


Figure 8-10 


LINK Command for FORTRAN Program Using Shared COMMON 


SGOWNI JTEVayVHS 


Tte-8 


MAIN 


Module Name 
SHRSUB 

MAIN 
OTSSLINKAGE 
SYSVECTOR 


Idant 
oEXES1 
a1 
19803 
3219 


aDBB2s [GOLDMAN] MAIN, EXE ss} 


Cluster 


SHRSUB 


VMSRTL 


DEFAULT, CLUSTER 


Type Pages 


rin fw ww & 


was > 


wee oe 


193 


See ee ee 


220FEB01988 14:27 


FP eases eseeeesrggvesuensast 


1 Object Module Synoosis | 


evens esseesuseessesaserat 


Bytes 


File 
a2 ,DB823 [GOLDMAN] SHRSUB,EXE;) 
4332 ,DBB23 [GOLDMAN] MAIN, OBJ31 
3 ORAS: (SYSLIB] STARLET.OLBs3 
@ ,ORASs CSYSLISB] STARLET, OLB31i 


22eFER@198G 14227 


teeweusserwesesenaeeennent 


! Image Section Synoosis } 


$m ewe men nena ecenwunsecenanty 


Base Adgr Ofsk ySN PFC Protection and Paging 


weseweases Cerrar ee ees exeveresseneeuernececa 


ABAINESY a 2 READ WRITE COPY ON REF 
BBa01024 a @ READ ONLY 

Beaarl2ryu @ ¥@ READ WRITE 

BORD1ARe ® @ READ ONLY 

2eeaicee 5 @ READ WRITE COPY ALWAYS 
BQBALESG @ 14 READ ONLY 

3009340e 6 @ READ ONLY 

20018600 ¢@ @ READ WRITE COPY ON REF 

- 3008G208 2 @ READ ONLY 

agavesae 3. @ READ WRITE COPY ON REF 
BABSBEBT 4 @ REAQ ONLY 

TFFFOS8aG @ @ READ WRITE DEMAND ZERO 
Figure 8-11 Map 


Creation Date 

ae eqaneueceave2een 
228FE8e198O 14226 
22°Feoei98A 14226 
19=FEBe{96S 21457 
19°FEB=1988 21:59 


LINKER 


Global Sec, Name 


SHRSUB, 001 
SHRSUB, 202 
SHRSUB, 393 
SHRSUB, 804 


VMSRTL, 221 
VMSRTL,@@2 
VMSRTL, O83 


LINKER v22,48 


Creator 


LINK@=32 ¥O2,48 


Page 


VAXe11 FORTRAN 71,9536 


VAXe4d1 Macro V82.41 
VAXw31 Macro V82,41 


V@2.48 


Matern 


EQUAL 
EQUAL 
EQuaL 
EQUAL 


LESS/EGUAL 
LESS/EQUAL 
LESS/EQUAL 


of FORTRAN Program Using Shared COMMON 


Majorid 


244 
e486 
2u4 
244 


Page 


Hinorid 


6260915 
8208915 
8260915 
8260915 


2088 
2oue 
20028 


t 


2 


SHOWWI YIaVaUuVHS 


ce-8 


aDPBB2: [GOLOMAN) HAIN, EXEs1 


Paect Name 
SPDATA 
SLOCAL 
SCODE 


aOTSSCODE 


« BLANK , 


LOCAL COMMON 


GLOBAL, COMMON 


Module Name 


MAIN 


MAIN 


MAIN 


OTSSLINKAGE 


OTSSLINKAGE 
SYSVECTOR 


SHRSUB 
MAIN 


SHRSUB 
MAIN 


Base 


Beadaede 
dAsea2nn 


“W4ueawde 
O4d3AdHD 


dUeAdbYY 
ReA“eERaA 


BdCaveTa 
OGAPR674 


Bee4eauA 
BIB2ABUR 
BAbAG8uUd 


DAAARBAG 
02096830 
yaaapaue 


#daA@laaa 
eear1aav 
64001299 


22-FEGe198H 14:27 


few wees n ew eenn sw eneesuneets 


1 Program Section Synopsis } 


wee eeneceeeseses ses eeeewest 


End 


eeGaesd 
PAUCR2S4 


AUaAe ate 
ouaenalFe 


BBYURGOT2 
AGGAGET2 


¢Q000676 
ABAAAETE 


eaneebed 
8090868 
“ouee8ed 


COUSaFFF 
28003808 
AABOUFFF 


GdASLAGs 
aaai2es 
89801403 
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Length 


a2eeeess 
aaaeaess 


aeadavee 
Gadgones 


GABABY73 
4AA88073 


BABABABS 
BABBBABS 


aaagerea 
222802098 
a2aoenRe 


22202820 
egaeanuse 
aaaaaser 


“aaoeoR8a4 
a2eQesae 
aeseaeaeud 
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¢ 
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¢ 


aw ran 


ae 


Alfan 


LONG 
LONG 


LONG 
LONG 


LONG 
LONG 


LONG 
LONG 


BYTE 
BYTE 
BYTE 


LONG 
LONG 
LONG 


LONG 
LONG 
LONG 


uwnw ww gQae ui Nr wr LY 


LINKER V¢@2,48 


attributes 


PIC,USR,CON,/REL»LCL, 


PIC,USR,CONsRELS LCL 


PIC,USR»CONsREL,LCL, 


PIC,USR, OVR,REL,GBL, 


SHR, NOEXE, 


PIC, USR»CONeREL- LCL, NOSHR, NOEXE, 


SHR,» EXEs 


SHR, EXE, 


NOPIC,USR,pCON,REL»LCL»NOSHR, EXE, 


PIC, USR, OVR, REL, GBL, NOSHR, NOEXE, 


SHR, NOEXE, 


Page 3 


RO, NOWRT, NOVEC 


RO, WRT,NOVEE 


RD, NOWRY, NOVEC 


RD, NOWRT, NOVEC 


RO, WRT,NOVEC 


RO, WRT,NOVEC 


RO, WRT,NOVEC 


SHOVWI a IGVaUVHS 


€€-8 


20BB2:s [GOLDMAN] MAIN,EXEs} 


Sympol 


2@eeFER=198A 14327 


$e sennewesoewssansy 


$ Symbols By Name | 


-uevesuaveeeesvaecat 


Value Symbol Value Symbol 
BASSSBLNK,LINE ageaegageRu SASSINSTR BSAU2OBG0RU BASSSCRATCH 
BAS$SCB_GET AEBAZIA ABR BSASSIN OR AAUB2TFOeRY BASSSTATUS 
BASSSCB,POP SAVIZ9T GORY BASSIN FR DIDA2TEBERY BASSSTR,D 
s . e e e 
. s . s e 
. ° ° e 


a0BB2: [GOLDMAN] MAIN, EXES1 


Value 

28OC8622 ReMAIN 

2Qa0Kd674 ReBASSLINKAGE ReFORSLINKAGE 
ABBALAGS RUPSHRSUB 


22eFEBo198A 14327 


PoP TTITTITTrrT Trey 


i Symbols By Value | 


Peer esvevseerveseVeSss 


Symbol seee 


Key for special characters abovet 
Peseesveqeuunevunent 
i* © Undefined i 
1U © Universal i 
[| R © Relocatable } 
i WK © Week i 


Puccevecsusevessecss 


Figure 8-11 (Cont.) 


ReOTSSLINKAGE 


LINKER V22,48 


Value 
CAAD29GHeRY 
420293 8-RU 
2802260 8=RU 
e 
« 


LINKER Vu2,40 
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Sympol 


FORSSCB,PUSH 
FORSSCB,RET 


FORSSERRSNS SAV 


Page 4 


Yalue 
48202408=RU 
26202418"RU 
ABAB2U2BeRU 

e 

. 

e 
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40BP2: [GOLDMAN] MAIN, EXES1 


2@2—FEB=1988 141827 


Fweeeaveevesenaeaeat 


tl Image Synopsis | 


feenseonaguaesasanat 


Virtual memory ajlocated3s 


Stack size: 23. paces 

Image header virtual black limits: le 1. ¢ 
Image binary virtual Block limits? ae 5. ¢ 
Image mame and identifications MAIN @Y 

Number of filess 4, 

Number of modules: Se 

Number of program sections? i3. 

Number of global symboiss 434, 

Number of image gections? 13, 

User transfer address? DAPBE dA 

Debugger transfer address! Baer 4168 

Image tyre: EXECUTABLE, 


Man format: 
Estimatea map lengths AB, blocks 


@OBNG2eR ZUGIBOFF BBB1BCeA (113664, 


1. block) 


4, clocks) 
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i Link Rum Statistics | 


peemeanenae seesaw eenent 


Page Faults 


Performance Incicators 


Command processing: ea 
Pass 13 382 
Allocation/Relocatian: 73 
Pess 2: 51 
Map data after object module synoosis?: 163 
Symbo)} table outputs: 13 
Total pun values: 626 


CPU Time 

@G30073G0,11 
20:00:01,328 
OA200200,26 
09'00309,268 
O2:60202,u9 
O8208808,a4 
O0200304,45 
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cytes, 222. pages) 


FuLL im f4le " Oae2: [GOLDMAN] MAIN, MAP 31" 


Elessed Time 
Sanat aqgeuaengces 
90000301,289 
201002605.82 
00:00300.75 
@0:08:02.19 
@2:00885.19 
Q83003003.56 
083200314,88 


Using e working set limited to 344 panes ani 58 cages of aata storage (excluding image) 


Total number object peceras read (both passes) 219 


of which 67 were in libearies and 4 were DEBUG data recoras containing 139 bytes 


124 bytes of DEBUG cate were written,starting at VAN 6 with 1 blocks allocated 


Numper of modules extracted explicitly = @ 
with 2 extracted to resolve undefined symbols 


@ library searches were for sympols mot in the library searched 
A total of @ global symbo) table recaras was written 


JEXESMAIN/MAPEMAIN/FULL MAIN, SYSSINPUTs /OPTIONS 


Figure 8-11 (Cont.) Map of FORTRAN Program Using Shared COMMON 
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8.5 USING SHAREABLE IMAGES 


To be of use, shareable images are normally linked into another image. 
Usually shareable images are installed by the system manager to make 
them available to the cooperating users at run time. Installation of 
shareable images is dealt with in the VAX/VMS System Manager's Guide. 


You must use an options file (see Chapter 5) to specify a shareable 
image as input to the _ linker. In an options file the /SHAREABLE 
qualifier becomes a legal input file qualifier, identifying the 
associated file as a shareable image. The /SHAREABLE qualifier 
optionally accepts the keywords COPY or NOCOPY, specifying whether the 
linker is to create a private copy of the shareable image in the user 
image. The default value is that no copy is produced. 


When an executable image is linked with a shareable image, the 
shareable image is assigned virtual address space in the executable 
image. But the linker does not copy the shareable image binary into 
the executable image file unless COPY is specified. 


When an executable image that is linked with a shareable image is run, 
the image activator opens the shareable image and checks the global 
section match, as described in Section 8.2.3. If the match succeeds, 
the image activator maps the shareable image into the assigned virtual 
address space. One of two things happen depending on whether the 
Shareable image has been installed with the /SHARE qualifier. 


If the shareable image has been installed with the /SHARE qualifier, 
all processes share the same copy of the shareable image in physical 
memory. If the executable image references a page of the shareable 
image that is not currently in physical memory, that page is read in 
from the shareable image. If the executable image references a page 
that is already in physical memory, that page is used. Note that once 
a page of a shareable image is read into physical memory for one 
process, any other process can use the same page in physical memory. 


If the shareable image has been installed without the /SHARE qualifier 
or if it has not’ been installed, or if the global section has the 
copy-on-reference attribute, the image activator creates a _ private 
copy of the shareable image. In this case, the private copy of the 
shareable image is treated as part of your executable image. Each 
process that is linked with the shareable image must have its own copy 
of the shareable image in physical memory. 


If the match fails, the image activator displays an error message 
indicating that the required global sections are not available. 


If the image activator cannot find the shareable image and if the 
executable image has a private copy of the shareable image, that copy 
is used. But if the executable image does not have a private copy, 
the image activator displays an error message indicating that the 
shareable image was not available. 


Note that, if the image activator finds a shareable image and _ the 
match fails, it will not use a private copy even if one is present in 
the executable image. 


SHAREABLE IMAGES 


NOTE 


The image activator assumes that both 
installed and uninstalled shareable 
images are in the directory defined by 
the logical name SYSSSHARE. If you want 
to use a shareable image that is in 
another directory, you must assign the 
file specification of the shareable 
image to the name of the shareable 
image. Note that you should assign’ the 
complete file specification, including 
the device and directory. For example: 


$ ASSIGN DBAO: [TEST] SHRSUB.EXE SHRSUB 
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LINKER MESSAGES 


This appendix lists the code and text portions of messages that the 
linker can issue. The messages are listed in alphabetical order by 
code. 

The messages are designed to give you all the necessary information 
about the error. Brief explanations are included for a few messages 
that are not self-explanatory. 

BADCCC, Module "[name]" has bad compilation completion code = [code] 
BADIMGHDR, Bad shareable image header in file "[file-spec]" 


BADPSC, Module "[name]" has transfer address in unknown P-section 
"[number]" 


BASESYM, Base address symbol "[{name]" is undefined or relocatable 
CLOSERR, Close failure on "[file-spec]" code = %X[error code] 


CONFMEM, Conflicting virtual memory requirement at $%X[address] for 
{number of] pages for cluster "[name]" 


CRE8ERR, Failed to create file “[file-spec]" 


CRFERR, Error code $%Xferror code] received from Cross’ Reference 
Facility 


DBGTFR, Image "{file-spec]" has no Debugger transfer address 
DIAGSISUED, Completed but with diagnostics 

EMPTYFILE, File "[{file-spec]" contains no modules 

ENDPRS, Parameter parse completion error, code = %X[error code] 
EOMFTL, Module "(name]" specifies Linker abort 


EOMSTK, Module "[name]" leaves [number of] items on Linker internal 
stack 


ERRORS, Module "(name)" has compilation errors - image deleted 
EXCPSC, Module "[name]" defines more than 256 P~sections 


EXCSPAR, Too many parameters in option: foption name] of file 
"[file-spec]" 


FAOBUG, FAO failure 


LINKER MESSAGES 


FATALERROR, Fatal error message issued 
FIRSTMOD, First input being a library requires module extraction 


FORMAT, File "[file-spec]" has illegal format 


GSDTYP, File "(file~spec]" has an illegal GSD record (type = [type 
code]) 
ILLFMLCNT, Min. arg. count of [number] exceeds max. ({number]) in 


formal spec. of "froutine name]" 
ILLKEY, Unrecognized keyword in parameter of option file "[file-spec]" 
ILLQUALVAL, Illegal qualifier value 


ILLREP, Module "[name]" has store repeated count [number] greater than 
{number ] 


ILLTIR, Module "{name]" has illegal relocation command = [number] 
ILLVAL, Illegal parameter value in option file "(file-spec]" 


ILLVPS, Module "{name]" contains illegal position ([{number]) or size 
({number]) in TIRSC_STO_VPS command 


INITPRS, Parameter parse initialization error, code = %Xferror code] 


INSVIRMEM, Insufficient virtual memory for [number of] pages for 
cluster "[name]" 


INTSTKOV, Linker internal stack of [number of] items overflowed by 
module "[name]" 


INTSTKUN, Linker internal stack of [number of] items underflows’ in 
module "[name]" 


IVCHAR, Invalid character in parameter - option file "[file-spec]" 


LIBFIND, Failed to find valid lib. mod. or shr. image STB. at RFA 
%X [address] %Xfaddress] 


LIBFMT, Library "(name)" (format = [bad format]) has incorrect format 
(not =[correct format]) for this Linker 


e Might be caused by a corrupt library or an attempt to use an 
RSX-11M library. 


LIBNAMLNG, Library module name length ([number of characters])) is 
illegal 


LINERR, Command line segment in error 
\ferror]\ 


MATCHID, Global section match ident’  (([number)) exceeds maximum 
({number]) 


MAXCHANS, [number of] channels exceeds maximum allowed of 64 


MAXIOSEG, [number of] I/O segment pages exceeds maximum allowed of 
65535 


MAXISDS, [number of] I-sections exceeds maximum allowed of 65535 


LINKER MESSAGES 


MAXPFC, Page fault cluster factor of [number] exceeds maximum (255) 
MAXSTACK, [number of] stack pages exceeds maximum allowed of 65535 
MEMBUG, Memory (de)allocation bug [description] %X[address] 

e Internal linker error 


MEMFUL, Linker virtual address space insufficient to complete this 
link 


MINDZRO, [number of pages] as minimum I-section size exceeds maximum 
allowed of 65535 


@ DZRO_MIN option value too high 


MODNAM, Illegal module name of [number of] chars. - not 1 to’ [number 
of] chars. 


MSGERR, Linker has error message bug [hex data] 
MULDEF, Symbol "{name]" multiply defined by module "[name]" 


e The named module defines a symbol that another module has 
already defined. , 


MULPSC, Module "[name]" has conflicting specifications for P-section 
"[name]" 


e A previously encountered module has already defined the 
program section with other attributes. 


MULTFR, Module "([name]" multiply defines transfer address 
e The named module defines the image transfer address (starting 
point), but a previously processed module has already defined 
the transfer address. 


SPNAMLNG, Illegal symbol/P-section name of [number of] chars. - not l 
to [number of] chars. 


NOEOM, Module "(name)" not terminated with EOM record 


NOEPM, Module "[name]" references undefined entry mask of symbol 
"(name)" 


NONBTAB, Non blank/tab between continuation and comment or end of 
record in "({file-spec]" 


NOMODS, No input modules specified (or found) 
NOPSCTS, No P-sections defined in module “" [name] " 
NOSUCHMOD, Library "(name]" does not contain module "{name]" 


NOTPSECT, Module "[name]" sets relocation base to other than a 
P-section base 


NOVALU Values not allowed in qualifier - option file "[file-spec]" 
NUDFSYMS, "(number]" undefined symbol(s) 


NULFIL, Null parameter in option file "(file~-spec]" 


LINKER MESSAGES 
NULPAR, Missing required parameter in option line [erroneous line] of 
file "({file-spec)" 
OPIDERR, Pass [number] failed to open file "{file-spec]" 


OPTREDERR, Read error (code=%X[error code]) on option file 
"({file-spec]" 


OUTSIMG, Attempted store location %X[address] is outside "fregion]" 
(8X[base address] to %X[ending address]) 


e "Region" is expressed as either "image binary" or "Debug 
Symbol Table." 


OVRALI, Module “f{name]" has conflicting alignment on overlayed 
P-section "{name]" 


PARMDEL, Invalid parameter delimiter in option file "[file-spec]" 
PRIMIN, Input parameter parse error, code = %Xferror code] 

PRIMOUT, Image file specification error, code = %X[error code] 

PSCALI, Illegal P-section alignment [number of bytes] - exceeds a page 
PSCNXR, Transfer address in "[module-name]" not in EXE/REL P-section 


@ The transfer address is normally in a program section with the 
executable and relocatable attributes. 


PSCOVFLO, P-section "[name]" overflows region to %X[address] 


RECLNG, File "[file~spec]" contains record of illegal length (fnumber 
of] bytes) 


RECTYP, File "[file-spec]" has an illegal record (type = [type code]) 
REDERR, Read failure in pass [number] on file "[(file-spec]" 

SECOUT, Map file specification error, code = $X[error code] 

SEQNCE, Illegal record sequence 

SHRINSYS, Shareable image(s) cannot be linked into a system image 


STRLVL, LINK [version] does not implement OBJ level [structure level] 
- only to [structure level] 


e The version of the object language is not compatible with the 
current version of the linker. 


STKOVFLO, Stack of [number of] pages falls below control region to 
%X [address] 


TFRSYS, Transfer address in system image "[file-~spec]" ignored 


TIRLNG, Module "(name]" has relocation command data ([number of] 
bytes) overflowing record 


TIRNYI, TIR command [number or name] not yet implemented (module 
w [name] ") 


LINKER MESSAGES 


TRACIGN, Suppression of traceback overridden by DEBUG specification 
e Occurs when you specify /NOTRACEBACK and /DEBUG. 
TRIOUT, Symbol table file specification error, code = %X[error code] 


TRUNC, Trunc. error in module "[name]", P-section "[name]", offset 
%X [hex value] 


TRUNCDAT, Computed value = %Xf[hex value], value written = &%X{hex 
value] at %X[address] 


UDEFPSC, Attempt to reference P-section no. [number] undefined in 
"“[module name]" 


@ Undefined program section 
UDFSYM, "[symbol name]" 
e Undefined symbol 


UNMCOD, Initial file name was "[file-spec}", RMS error code = %X[error 
code] 


UNRECOPT, Unrecognized option in file "{file-spec]" 

UNRECQUAL, Unrecognized qualifier in option file "[file-spec]" 
USEUNDEF, Module "[name}]" references undefined symbol "[name]" 
USRTFR, Image "[file-spec]" has no user transfer address 

WRNERS, Module "[name]" has compilation warnings 

WRTERR, Write failure on file "[file-spec]", code = %X[error code] 


VALREQ, Value required in qualifier - option file "[file-spec]" 
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IMAGE MAP ILLUSTRATIONS 


This appendix illustrates the brief, default, and full forms of a map 
of the same image. 


In addition, after the full form of the map, a Symbol Cross Reference 
map section is illustrated. 


The image map is described in Chapter 6. 
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Bytes File 
seavse zeae 
388 ,0BB2t (GOLDMAN) DEMO, 08J;2 
179 .DBB2s (GOLDMAN) $U81,08J;2 
23 .DBB2s (GOLDMAN) FUN1,0BJ31 
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26eFeb=1968 10316 
2oeFeb=1968 16915 
26Febe1980 18215 
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Creator 
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VAX=il FORTRAN T1,95=36 
VAK=11 FORTRAN 1T1,95036 
VAXe11 FORTRAN T1,95=36 
VAXed1 FORTRAN 1T1,95836 


dVW A31ug 


SNOILWULSNATTI dWW FOVWI 


a0BB2t (GOLDMAN) DEMO,EXEp1 


Virtual memory allocated! 

Stack sizes 

Image header virtual block limits: 
Tmage binary vietual block Timitss 
Image name and identifications 
Number of files? 

Number of modules: 

Number of program sections? 

Number of global symbols: 

Number of image sections! 

User transfer address? 

Devugger transfer address} 

Image typet 
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23, cages 
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4. ¢ 3. blocks) 
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Estimated map lengths: @, blocks 
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Performance Indicators Page Faults CPU Time 

Seasegeuseeecaasteacen eust eS BVaeaut seu seeuesaeo 
Command processing: 17 ée2e03@0,168 
Pass i: 195 08300290,95 
Allocation/Relocation: 25 @0:08290,11 
Pass 22 33 90200200, 32 
Map data after object module synopsis? : a 08:20308,00 
Symdol table output; 4 08300200,82 

Total run values: 274 02500301,56 


GRIEF in file ",0682: [GOLDMAN] DEMOBR, MAP; 2" 


Elapsed Time 
@0:220%98,69 
08:90:348,31 
08:00206,44 
02:00:12,98 
03300360,80 
00:281303,54 
88201919,96 


Using @ working set limited to 242 pages and 49 pages of deta storage (excluding image) 


Total pumper object records read Cooth passes)! 183 


of which Si were in libraries and & were DEBUG data recorda containing 189 bytes 


169 bytes of DEBUG date were writtensstarting at VAN 5 with 1 bloeks allocated 


Number of modules extracted exolicitly 228 
with 1 extracted to resolve undefined symbols 


@ library searches were for symbols not in the library searched 
A total of @ global symbol table records was written 
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203.) LONG 
64.) LONG 
99.) LONG 
19.) LONG 
19.) LONG 


BG.) BYTE 
Oe.) BYTE 


aa tw fy 0% fury NNN ND FN Py fe 
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Attributes 


PIC;USReCONPRELe LCL, SHR»/NOEXE, 


PIC, USR» CON, REL + LCL» NOSHR,NOEXE, 


PIC,USR,CONPREL,LCL,» SHR, EXE, 


NOPIC,USR,CON,REL»LCL»sNOSHR, EXE, 
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RD, NOWRT, NOVEC 


RD, WRT,NOVEC 


RD, NOWRT, NOVEC 


RD, WRT,NOVEC 
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2DBB2s [GOLDMAN] DEMO,EXEs3 


Symbo} 
BASSSBLNK LINE 
BASSSCE,GET 
BASSSCB,POP 


e 
BASSINIT,R8 
BASSINPUT 
BASSINPUT LINE 


Value 
BRBALZAGH=RU 
@00013808RU 
A@G00137BeRU 
e 
e 


J 
BOUSLL18eRU 
GGBA1LaBeRU 
B@AAL1IBASRY 
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Symbol Value Symbo! 
BASSINSTR A091 GBR=RU BASSSTATUS 
BASSIN, DR OBOOLIFAeRU BASSSTR D 
BASSIN,F LR OABALIEB=RU BASSSTRF 

e : e r) 

‘J e iJ 

e e e 
BASSRSET R AQBALAABeRU DEMa 
BASSSCALE,D,R1 @8201278eRU FORSSCB,GET 
BASSSCRATCH BQOA13508=RU FORSSCB,POP 


Value 
88OA13389RU 
@2981eCe=RV 
SO0210B8=RU 
. 
J 


e 
@8820600eR 
@SSOCE2G=RY 
@AGBZELa=RU 


Symbo} 
FORSSCB_ PUSH 
FORSSCB,RET 
FORSSERRSNS SAV 
. 
e 


s , 
FORSIO,B,R 
FORSIO,8,¥ 
FORSIO,OC.R 
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Value 
eecun 
COCOGEGBRU 
@2S04E18=RU 
OB2AGE2B-RU 
e 
e 


e 
@B4eGSEBeRU 
OBSBSBEB=RU 
@B200928eRU 
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oT-d 


20BB2s (GOLUMAN] DEMO,EXE 93 


Symbol 
@eeuanre@ 
FORSIO,0C,V 
FORSIO,0,8 


Su61 
SYSSIMGSTA 


Value 
ANBABESG=RU 
4088G8CBeRU 


s 
SOG2064a=R 
6a00a168 


Value 
OBUBHBEA4OR 
BAAGA6BE-R 
e 
e 
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Symbol 
MTHSASIN RS 
MTHSATAN 

e 
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Value 
meagan 
BUGOBAAG@RU 
OASECAASHRY 
e 
e 
e 


Symbol 
aee8ens an 
OTSSCVTLLLTZ 
OTSSCVTLTIaL 
« 
e 
e 
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Value 
OBCOHMEABRU 
BAGBRALZ=RU 

e 

e 

e 
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Value 

BBeadebo 
oge0%6da 
BAG0BEA4 
aoeeaebs 
Ceagv8a0 
Geaabsus 


e 
802900168 


26°FEB21989 18328 


PFoeseveavveszseveven} 
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¢scecesgaaeusceoaveest 


Symbol@ece 


R=DEMO 

R=SUBY 

ReFUNI 

ReFUN2 
RU*FORSCLOSE 
RU@FORSDECODE, MF 


SYSSIMGSTA 


Key for specia) characters above; 
-euecuscvescuaseuusy 
is © Undefined 4 
iu = Universal é 
sR = Relocatable ! 
to WK © Weak i 
+ 


fueevesees esaacnesee 


LINKER V82,49 


Page 


7 


dVW TINA 


SNOILVULSNITI d¥W FOVWT 


éT-d 


aD BB2: (GOLDMAN) OEMO,EXE;3 


Virtual memory allocated: 

Stack sizes 

Image header virtual block timitss 
Image binary virtual bloek limites 
Tmage name and identification: 
Number of files: 

Number of modyles: 

Number of program sections! 

Number of global) symbols: 

Number of {mage sections? 

User transfer eddress! 

Debugger transfer address? 

Image typet 

Map formats 

Estimated map length: 


Performance Indicators 


26eFEB21980 18328 


Pasaeneuseesenesse+ 


i Image Synopsiea | 


Puveuevsvgrveusauat 


BGG8G200 BBGLATFF GOCI1AbGS (188032, bytes, 211. pages) 


28, pages 
i. i. 
2e 4, 
DEMO O14 


8. 
28088602 
62000168 
EXECUTABLE, 


1, bloek) 


3, bloeks) 


FULL in file ",0B62: [GOLOMAN) DEMOFULL, MAP s2* 


58. blocks 


-resquavevsecarasasevasety 


J Link Run Stetistics } 


Peaseaseqnveuasneaseveat 


Page Feulta 


Command processing: 17 
Pass 13 259 
Allocation/Relocations Te 
Pass 2% 69 
Map date after object module synonais: 91 
Symbol] table output; 8 
Tote! run values? 516 


CPU Time 

O@:00:90,15 
@23080301,15 
06300200,30 
92220200, 31 
O@1G0301,98 
B2:AG28a,Aas 
@0200383,92 


Elecsed Time 
een anavacerns 
00:00:05,087 
OOs00827,61 
Q0300207,65 
O2:@0313,22 
@0200833.31 
06:08:84,807 
60281238,93 


Using a working set. limited to 237 peges and 49 pages of data storage (excluding tmage) 


Tota! mumber object records pead (both passes) } 183 
of which Si were in tibraries and 8 were DEBUG dats records containing 189 bytes 


169 bytes of DEBUG data were written,starting at VBN 5 with 1 blocks allocated 


Number of modules extracted explicitly 


z 8 


with 1 extracted to resolve undefined symbols 


@ \ibrary searches were for symbols mot in the tfbrary searched 


A total of ® global symbol table records was written 


/MAPEDEMOFULL/FULL DEMO,SUB1,FUNI,FUN2 
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€1t-d 


0882s [GOLDMAN] DEMO,EXE;4 


Symbo! 


BASSSBLNKLINE 


BASSSCB,GET 


s 
DEMO 
FORSSCB,GET 
FORSSCB,POP 

* 

° 


¢ 
FUN1 
FUN2 

e 

e 


e 
SUBI 
SYSSIMGSTA 


Value 


eusen 

O@BBG13AG=RU 

@008138e=eRU 
e 


e 
@aG0B60GeR 
BBQGBE2GeRU 
@AG6OBEa=RU 

s 

e 


e 
BAGAG6AGHR 
BOARBEBS=R 

s 

a 


avacoedo~R 
82000168 


Defined By 


DEMO 
VMSRTL 
VMSRTL 


FUNL 
FUNe 


SUBL 
SYSVECTOR 
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APPENDIX C 


VAX-11 OBJECT LANGUAGE 


The object language description in this appendix is taken from DIGITAL 
software specifications. This appendix is useful for anyone writing a 
compiler or assembler that must generate object modules acceptable for 
input to the VAX-11 Linker. The object module analysis program 
(ANALYZE), discussed in Appendix D, checks an object module to see if 
it conforms to the requirements in the DIGITAL software 
specifications. 


C.1 INTRODUCTION 


The VAX-11 object language is accepted by VAX-11 linkers, object 
module librarians, and object patch utilities. 


The object language described herein is for use by all VAX-11 family 
software -- that is, no subsetting will occur. All language 
processors that produce code for execution in native mode are free to 
use any or all of the described object language. 


C.1.1 Summary of Language 


Object modules are the input to the linker and are obtained from the 
various language processors as individual files or as object library 
files. All symbol table files created by the linker are also in the 
format specified here. 


An object module consists of an ordered set of variable-length 
records, of which the following types are defined: 


OBJSC_HDR 0 Header Record (HDR) 

OBJ$C_GSD = 1 - Global Symbol Directory Record (GSD) 
OBJ$C_TIR = 2 - Text Information and Relocation Record (TIR) 
OBJSC_EOM = 3 - End of Module Record (EOM) 

OBJ$C_DBG = 4 - Debugger Information Record (DBG) 

OBJ$C_TBT = 5 - Traceback Information Record (TBT) 


OBJSC_LNK = 6 - Link Option Specification Record (LNK) (Currently 
ignored) 


Refer to Figure C-1 for an illustration of the order in which’ records 
appear in the object module. 
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Module Header Record 

Global Symbol Directory Record 

Text Information and Relocation 
Records 


Additional Global Symbol Directory 


Debugger Information Record 
Traceback Information Record 

More Text Information and Relocation 
More global symbol information 

More text 


End of Module 





Figure C-l Order of Records Within an Object Module 


It is mandatory that there be at least two HDR records, a Module 
Header Record (MHD) and a Language Name Record (LNM), and exactly one 
EOM Record. These records must’ begin and end the module, 
respectively. Within the module, there must’ be at least one GSD 
record and there may be any number of TIR, DBG, TBT and LNK_ records. 
As is described below, some ordering is implicit within the set of GSD 
records. 


In this document, the term "reserved" implies that the item must not 
be present because it is reserved for possible future use by the 
linker and DIGITAL. The linker produces an error if a reserved item 
is found in an object module. 


All unused and ignored fields of records must be padded to conform to 
the block lengths specified in this document. The content of such 
fields will be completely ignored by the linker and any other 
processors. 
The remaining possible language record types are allocated as follows 
but not defined in this document: 

Type 7-100 Reserved for future use by linker 

Type 101-200 Ignored always 


Type 201-255 Reserved for customer use 
(Ignored by current implementation) 
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C.2 GLOBAL AND UNIVERSAL SYMBOLS AND NAME FORMAT 

The linker deals with two types of symbols, global and universal. 
Global symbols are those that are accessible to more than one module 
of the set being linked. Universal symbols are a subset of the global 
symbols, They are ones that the linker retains when linking an image 


to which another set of object modules and/or images will subsequently 
be bound. 


The Object Language also deals with the names of program sections and 


object modules and may contain the names of language processors and 
utilities. 


All names are represented by a l-byte character count followed by the 
ASCII character string. 


The current implementation of the linker limits such name strings to 


31 characters, except in the case of header record types 1-255 (see 
Section C.3.2). 


C.3 HEADER RECORDS (HDR) 


The object language defines a general class of header’ records. The 
Module Header Record (MHD) is described in Section C.3.1. 


The Language Name Record and the remaining header types are described 
in Section C.3.2. 


C.3.1 Module Header Records (MHD) 
The module header records (MHD) collect in one place all module-wide 
information. The module header records are needed by the librarian 
and patch utilities and permit future expansion of the object 
language. 
The MHD (Module Header Record) record contains the following 
information in the format shown: 

RECORD TYPE 0 1 byte 

HEADER TYPE 0 1 byte 

STRUCTURE LEVEL 1 byte 


MAXIMUM RECORD 
SIZE 2 bytes 


MODULE NAME Variable (2-32) 
MODULE VERSION Variable (2-32) 


CREATION TIME 
AND DATE 17 bytes 


. TIME AND DATE 
OF LAST PATCH 17 bytes 
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All entries are required. Detailed descriptions of the fields follow. 


C.3.1.1 Header Type - The MHD header type is 0 (OBJ$C_HDR_MHD). 


C.3.1.2 Structure Level OBJS$C STRLVL - It is intended that the format 
of the MHD record remain fixed from first implementation onward. The 
structure level is provided such that extensions to the language, 
which require changes to other record formats, can be dealt with 
without requiring recompilation of every module that conforms to the 
previous format. The structure level is zero. 


C.3.1.3 Maximum Record Size OBJ$C_MAXRECSIZ - The size in bytes of 
the longest record that can occur within this object module. The 
maximum size is 2048 bytes. 


C.3.1.4 Module Name - The module name conforms to the format of all 
other names, that is, length contained in a byte followed by an ASCII 
string. If the module is a symbol table created by tthe linker, the 
name will be the image name assigned at link time. 


C.3.1.5 Module Version - The module version conforms to the format of 
all names in the object language. 


C.3.1.6 Dates and Times - There are two date and time fields, one for 
module creation and one for the last modification to the module (by an 
object module patch utility). The format is a fixed 17-character 
ASCII string: 

dd-mmm~yyyy hh:mm 
where: 

dd = day of month 

mmm = standard 3-character abbreviation of month 


yyyy = year; note the space that follows 


hh = hour of day 00 to 23 


W 


mm minute of hour 00 to 59 
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C.3.2 Other Header Records 


The purpose of subheader records is primarily to contain optional 
textual information in printable form. Each record consists of a byte 
which is zero to indicate a header record, followed by a subtype byte. 
The following subtypes are defined. 


OBJ$C_HDR_LNM 


1 Language Processor (LNM) Name and Version. 
One record is required and limited for the 
current implementation to 35 characters. The 
content of this record appears on the link 
map output. 


OBJS$C_HDR_SRC = 2 List of file-specifications for the source 
files from which object module was created. 
Multiple records are permitted. (Currently 
ignored) 

OBJS$C_HDR_ TTL = 3 Title text (e.g., brief module description). 
Only one record permitted. (Currently 
ignored) 

OBJSC_HDR_CPR = 4 A copyright statement. Only one record 
permitted. (Currently ignored) 

OBJ$C_HDR_MTC = 5 Maintenance Status. (MTC) Multiple records 
permitted. (Currently ignored) 

OBJSC_HDR_GTX = 6 General Text. Multiple records permitted. 


(Currently ignored) 
Types 7-100 are reserved. 


Types 101-255 are always ignored. 


C.3.2.1 Header Types 1 through 4 and 6 - The purpose of these records 
is to allow the language processors to provide printable information 
within the object modules for documentation purposes. The only format 
definition is that the record contain printing ASCII characters. 
Types 4 and 6 may be generated by users, whereas types 1 through 3 are 
restricted to the language processors. 


C.3.2.2 Maintenance Status Header Record (MTC) - This record is of 
concern only to the object module patch utility and the object module 
analysis (ANALYZE) utility (see Appendix D). It is ignored by the 
librarian and the linker. 
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The format is as follows: 







































RECORD TYPE 0 1 byte 
HEADER TYPE 5 1 byte 
PATCH variable 
UTILITY NAME 2-32 bytes 
UTILITY variable 
VERSION 2-32 bytes 
UIC 2 bytes 
INPUT FILE variable 
SPECIFICATION 2-42 bytes 
CORRECTION FILE variable 
SPECIFICATION 2-42 bytes 

17 bytes 

1 byte 


C.3.2.2.1 Record Type - Zero signifies a header record. 


C.3.2.2.2 Header Type - The type is 5 signifying a maintenance status 
record. 


C.3.2.2.3 Patch Utility Name - This name identifies the patch utility 
used to perform this patch on the module. This field begins with one 
byte containing the number of bytes in the field (not including the 
count byte itself). 


C.3.2.2.4 Utility Version - The patch utility is further identified 
by its version number. This field begins with one byte containing the 
number of bytes in the field (not including the count byte itself). 


C.3.2.2.5 U.I.C. - This is the user identification code under which 
the patch was made. 


C.3.2.2.6 Input File Specification - This filename identifies the 
input file for this patch. This field begins with one byte containing 
the number of bytes in the field (not including the count byte 
itself). 
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C.3.2.2.7 Correction File Specification - This filename identifies 
the correction file for this patch. This field begins with one byte 
containing the number of bytes in the field (not including the count 
byte itself). 


C.3.2.2.8 Date & Time - This 17-byte field contains the date and time 
that this patch was performed. Format is as described above. 


C.3.2.2.9 Sequential Patch Number - This number is a sequential count 
of the patches made to this module. 


C.4 GLOBAL SYMBOL DIRECTORY (GSD) RECORDS (OBJS$C_GSD) 


Global symbol directory records contain all the information necessary 
to allocate virtual address space and to combine all the program 
sections into the separately protectable sections (image sections) of 
the image being created, 


GSD records are of the following types: 
OBJ$C GSD PSC 


OBJ$C_GSD_SYM 
OBJ$C_GSD_EPM 


0 Program section definition. 

1 Global Symbol Specification. 

2 Entry Point Symbol and Mask 
Definition, 

3 Procedure and Formal Argument 
Definition. 


OBJ$C_GSD_PRO 


Within any GSD record, there may be many entry types. In such cases, 
a single record appears as the concatenation of many, with the 
omission of the byte containing the Object Language record type (the 
value OBJ$C_GSD). 


C.4.1 Program Section Definition (OBJ$C_GSD_PSC) 


The format of a program section definition is as follows: 


RECORD TYPE 1 






















1 byte 
GSD TYPE 0 1 byte 
ALIGNMENT 1 byte 

2 bytes 
ALLOCATION 4 bytes 
PROGRAM SECTION Variable 
NAME 2-32 bytes 
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C.4.1.1 Program Section Name - This name has the same format as all 
other symbol names. 


C.4.1.2 Alignment - This field specifies the virtual address boundary 
at which the program section will be placed. The alignment is 2 to 
the power specified in the field. 


Value Alignment 
0 1 (BYTE) 
1 2 (WORD) 
2 4 (LONGWORD) 
3 8 (QUADWORD) 
4 2**4q 
9 2**Q9 (PAGE) 


Nine indicates page alignment and is the limit for program section 
alignment. 


Each module contributing to a program section can specify its own 
local alignment, with the restriction that program sections whose 
contributions overlay each other must all have the same alignment. It 
should also be noted that an alignment specified within a program 
section (for example, the assembler .ALIGN directive) must be less 
than or equal to the program section alignment to be guaranteed. For 
example, byte alignment of the program section may or may not cause 
longword aligned elements within the program section. 


C.4.1.3 Flags - The flag bits in the program section definition have 
the following meaning: 


Bit Name Meaning If Set 

0 GPSSV_PIC Program section defined as position 
independent. 

1 GPSSV_LIB The program section was defined in the symbol 


table of a shareable image, to which this 
image is bound. 


2 GPSSV_OVL Contributions to the same program section are 
overlaid. (The complement is concatenation). 
3 GPSSV_REL Program section requires’ relocation (the 
complement, bit=0, means absolute and 


contains only symbol definitions. Thus the 
allocation of an absolute program section is 
zero). 


4 GPSSV_GBL The scope of program section is global. (The 
complement is local). 


5 GPS$V_SHR Program section is potentially shareable 
between two or more active processes. 


6 GPSSV_EXE Content of the program section is executable. 
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Bit Name Meaning If Set 

7 GPSS$V_RD Content of the program section may be read. 

8 GPS$V_WRT Content of the program. section may be 
written. 

9 GPS$V_VEC Program section contains change mode dispatch 
vectors, 

10-15 Reserved. 


Discussions of program section attributes may be found in the related 
documents. (See also Section 7.5.4 of this manual.) 


C.4.1.4 Allocation Field - The allocation field contains the length 


contribution to the program section in bytes. It must be zero for an 
absolute program section. 


Program sections are assigned an identifying sequence number as' their 
respective GSD records are encountered. The program section number 
ranges from 0 through 255 within any single module, Note, however, 
that the total number of program sections in a single link operation 
is bounded only by the linker's virtual memory requirements. This 
program section number is used as an index in all references to the 
program section. Note that this permits any mixture of GSD records, 
as long aS program sections are defined to the linker in the same 
order as the index used by symbol definitions. 


C.4.2 Global Symbol Specification OBJ$C_GSD_SYM 


Global symbol specification records may appear anywhere between the 
MHD and EOM records and in any order. 


The format of a global symbol specification is as follows: 













RECORD TYPE 1 l byte 
GSDTYPE 1 1 byte 
DATA TYPE 1 l byte 
FLAGS 2 bytes 
PSECT INDEX 1 byte 
VALUE 4 bytes 
SYMBOL Variable 
NAME 2-32 bytes 


The 5 bytes for PSECT INDEX and VALUE are omitted for a reference. 
(that is, when SYMSV_DEF=0). 
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C.4.2.1 Data Type - The data type record is encoded as described in 
Appendix C of the VAX-11 Architecture Handbook. 





NOTE 


The current implementation of the linker 
ignores the data type field. 


C.4.2.2 Flags - The flag bits in the global symbol specification have 
the following meaning: 


0 for 

1 for 
Tabl 
in 
(GSY 


for 
for 


an) 


for 
for 
This 
defi 
be x 


eo 


for 
for 


KO 


Use 


strong resolution. 

weak resolution, 

e C-1 describes the use of GSYSV WEAK 
conjunction with the definition bit 
$V_DEF). 


reference 
definition 


within facility 
universal symbol 

bit is significant only on a 
nition. It indicates the symbol is to 
etained if this facility is shareable. 


absolute symbol value 
relative symbol and the value is 


augmented by the indexed program section 


base 
cont 


Rese 


address (of this module's 
ribution) 


rved. 


Table C-l 


Interpretation of GSYS$V_WEAK and GSY$V_DEF 








Bit Name 

0 GSYSV_WEAK 

1 GSYSV_DEF 

2 GSYS$V_UNI 

3 GSYSV_REL 

4-15 

GSY$V_WEAK 
0 0 
1 0 
0 1 
1 1 








GSY$V_DEF 






















Interpretation 
Strong Reference -- symbol must 
resolved 
Weak Reference -- resolved only if the 


symbol is defined for some reason 
other than this reference. Does not 
incur any searches’ or module loads. 
Has the value zero if undefined, with 
no error report. 


Strong Definition -- remains in all 
required symbol tables/maps. 


Weak Definition -- is discarded from 
all symbol tables/maps unless there 
was a reference. Does not appear in 
the global symbol table index of an 
object module library. 











c-10 
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C.4.2.3 Program Section Index - The program section index is a number 
between 0 and 255 to be used as an index into the sequence of program 
section definition records. This field exists only for symbol 
definition records (GSYSV DEF=1) and identifies the program section in 
which the symbol was defined. The index is also used in TIR commands 
(see Section C,.5.1.1) for reference to program section base addresses. 


All symbols encountered must be defined within a program section, 
independently of the relocatability of program sections or symbols. 
For example, the linker does not require the base address of the 
"owning" program section if the symbol is absolute. However, for the 
purposes of generating a readable map, it is very useful to maintain 


the hierarchy of symbol within program section within module within 
file. 


C.4.2.4 Value - This field contains the value assigned to the symbol 
by the language processor. This field does not exist if the record is 
a symbol reference (GSY$V_DEF=0). 


C.4.3 Entry Point Symbol and Mask Definition (OBJ$C_GSD_EPM) 


This format is an extended version of the global symbol definition 
format above. Following the symbol value (which will be an entry 
point address) is a two-byte field for the procedure's register save 
mask (as used by CALL instructions). The format is as shown below. 














RECORD TYPE 3 1 byte 
GSD TYPE 2 1 byte 
DATA TYPE 1 byte 

2 bytes 

1 byte 

4 bytes 
ENTRY MASK 2 bytes 
SYMBOL variable 

2-32 bytes 





C.4.3.1 Entry Mask - The entry mask is written at the entry point of 
a procedure entered via a CALLS or CALLG instruction, and in some 
cases also is used in transfer vectors to such. procedures. A TIR 
command (see Section C.5) is provided for the language processor to 
direct the linker to insert the mask at the procedure entry point or 
at the transfer vector. 


C.4.4 Procedure with Formal Argument Definiton (OBJ$C_GSD_ PRO) 


This GSD format is an extension of the entry point and mask definition 
format to define the formal arguments of the procedure. The format is 
as shown below. 
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RECORD TYPE 1 1 byte 
GSD TYPE 3 1 byte 
DATA TYPE 1 byte 
FLAGS 2 bytes 
PSECT INDEX 1 byte 
VALUE 4 bytes 
ENTRY MASK 2 bytes 
SYMBOL variable 
NAME 2-32 bytes 
eae eee | 

MINIMUM ACTUAL 1 byte 
ARGUMENTS 

MAXIMUM ACTUAL 1 byte 


ARGUMENTS 


variable length 
(2~256 byte) 
descriptors of 
formal arguments 
arg n is optionally 
function return 
value. 








FORMAL ARG n 
DESCRIPTOR 





Following is a description of the fields of a procedure definition 
different from the fields described in the other types of GSD records. 


C.4.4.1 Minimum and Maximum Actual Argument Counts - Permissible 
values are 0 through 255 and specify, respectively, the minimum number 
and the maximum number of arguments required for a valid call to this 
procedure. The counts must include the function return value if such 
exists. 


The current implementation does not validate procedure calls. 
However, for its own integrity, the current implementation validates 
that the minimum number of actuals is less than or equal to. the 
maximum number of arguments. The maximum number of actuals field is 
then used to process the formal argument descriptors. 
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C.4.4.2 Formal Argument Descriptors - Each of the formal argument 
descriptors of the record shown above has the following format: 





ARG. VAL. CTL. 1 byte ARGSB_VALCTL 





REM. BYTE CNT. 1 byte ARG$B_BYTECNT 





DETAILED variable 

ARGUMENT 0-255 bytes 
DESCRIPTION ignored by current 
implementation 





C.4.4.2.1 Argument Validation Control Byte - This (the first) byte of 
each formal description is used to control the validation of the 
argument. The only field of this control byte used by the linker is 
as follows: 


Bits 0:1 ARGSV_PASSMECH - Describes the mechanism by which the 
argument of a valid call must be passed. 


Bits 2:7 Reserved - Ignored by the current implementation. 


The following argument-passing mechanisms are defined: 


ARG SK_UNKNOWN = 0 Unspecified 
ARGS$K_VALUE = 1 By value 
ARGS$K_REF = 2 By reference 
ARG $K_DESC = 3 By descriptor 


C.4.4.2.2 Remaining Byte Count - This field gives the length of the 
remainder of this argument descriptor. For the current 
implementation, it is used as a count of bytes to be ignored by _ the 
linker. The content of these remaining bytes is reserved for possible 
future implementations. 


NOTE 


Any use of formal argument descriptors 
in which 


ARGS$B_VALCTL bits 2:7 NEQ 0 
and/or 

ARGSB_BYTECNT NEQ 0 
means that, should argument validation 
be implemented in a future VAX-11 


Linker, recompilation of all such 
objects may be necessary. 
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C.5 TEXT INFORMATION AND RELOCATION (TIR) RECORDS (OBJSC_TIR) 


Text information and relocation records contain a sequential series of 
commands and data for the linker to compute and record the contents of 
the image. The general form of a TIR record is as follows: 


RECORD TYPE 2 1 byte 


COMMAND 1 1 byte 









DATA 1 Byte count implied by command 





COMMAND l byte 


Byte count implied by command 





COMMAND 1 byte 








DATA N Byte count implied by command 


C.5.1 Commands 


The linker's creation of the binary content of an image file is 
completely driven by the language processor via the commands contained 
in TIR records. To achieve this, the linker maintains an internal 
stack. 


The commands available allow values to be placed on the stack and 
operations to be performed on the items on top of the stack. These 
commands also permit the writing of values from the stack to the 
output image. Other commands permit the storing of a sequence of 
bytes from object module to output image without alteration by the 
linker. They also provide for control of the relocation of the 
position currently being written in the image. 


In commands which refer to program sections, the names are identified 
by the sequence numbers assigned to them as described above. The 
program section indexes are in the range 0 through 255. 


The command byte has two formats: 











7 6 0 
FORMAT 1 [2] -COUNT | 
7 6 0 





FORMAT 2 lo COMMAND | 
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The only command with FORMAT 1 is the Store Immediate (STOIM), which 
merely causes the copying of the following bytes (given by the 
negative count in the range -1 through -128; into the output image. 


All other commands are described by the second format. There are four 
groups of commands: 


Stack Group 
Store Group 
Operator Group 
Control Group 


The stack on which these commands operate is longword aligned at all 
times. Furthermore, it must be completely collapsed at end of module, 
but is retained between all other record types. The minimum stack 
space available will be not less than 25 longwords. 


C.5.1.1 Stack Group - The stack group of commands provides the 
capability to store bytes, words, and longwords on the stack. The 
value placed on the stack may follow the command in the fTIR_- record; 
it may be found from a global symbol; or it may be computed from the 
base address of a program section. Except for stacking the value of 
global symbols or stacking addresses (calculated from program 
sections), both signed extension to longword and zero extension to 
longword are provided for byte and word stack operations. The codes 
in the following list are decimal. 


Code Command Description/Interpretation 
0 Stack Global Symbol specification follows. As 
(TIRSC_STA_GBL) with all other names, it consists 


of the symbol length in a byte 
followed by the ASCII string 
defining the symbol: 





LENGTH 1 byte 
SYMBOL Variable 
1-31 bytes 


The value found from the symbol 
table is a 32-bit quantity. 


1 Stack Signed Byte Single signed byte constant 
(TIRSC_STA_SB) follows. Value is sign extended 
to 32 bits. 
2 Stack Signed Word Single signed word constant 
(TIRSC_STA_Sw) follows. Value is sign extended 
to 32 bits. 
3 Stack Longword Single longword constant follows. 
(TIRSC_STA_LW) 
4 Stack PSECT base l-byte program section number 
plus byte offset followed by single signed byte 
(TIRSC_STA_PB) offset. A 32-bit quantity is 


computed by addition of program 
section base address and the byte 
offset. 


Code 


10 


ll 


12 
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Command 


Stack PSECT base 
plus word offset 
TIRSC_STA_PW) 


Stack PSECT base 
plus long word offset 
(TIRSC_STA_PL) 


Stack Unsigned Byte 
(TIRSC_STA_UB) 


Stack Unsigned Word 
(TIRSC_STA_UW) 


Stack Byte From Image 
(TIRSC_STA_BFI) 


Stack Word From Image 
(TIRSC_STA_WFI) 


Stack Longword From 
Image (TIR$C_STA_LFI) 


Stack Entry Point Mask 
(TIRSC_STA_EPM) 


Description/Interpretation 


l-byte program section number 
followed by single signed word 
offset. A 32-bit quantity is 


computed by addition of program 
section base address and the word 
offset. 


l-byte program section number 
followed by signed longword 
offset. A 32-bit quantity is 


computed by addition of program 
section base address and the 
longword offset, 


Note that although the offsets in 
the above three commands’ are 
signed, negative values are very 
rarely correct. Note also that 
the base address is that of this 
module's contribution to the 
program section. 


As for TIRSC_STA_SB except that 
the value is zero extended to 32 
bits. 


As for TIRSC_STA_SW except that 
the value is zero extended to 32 
bits. 


This command is’ reserved for 
future use. The longword on top 
of the stack is used as an 
address, in the image, from which 
to retrieve a byte. The byte is 
zero extended and replaces’ the 
top longword of stack. 


This command is’ reserved for 
future use. It is the word 
variant of the previous command. 


This command is’ reserved for 
future use. It is analogous’ to 
the previous two commands. 


This command has the same format 
as TIRSC STA GBL. However, 
instead of stacking the value of 
the symbol, the entry point mask 
(unsigned word) which accompanies 
the symbol definition is stacked. 
An error is produced if the 
symbol referenced is not an entry 
point. 


Code 


13 


14-19 
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Command 


Compare procedure 
arguments and stack 
TRUE or FALSE. 
(TIR$C_STA_CKARG) 


Reserved Commands 


Description/Interpretation 


The format of the command is as 
follows: 


COMMAND CODE 


SYMBOL 
NAME 


ARG INDEX 


ACTUAL 
ARGUMENT 
DESCRIPTOR 





The purpose of this command is to 
compare an actual argument 
descriptor with a formal 
descriptor for a particular 
procedure, stacking an indicator 
based on match or mismatch of 
arguments. This indicator is 
TRUE if match is found or if 
there is no formal argument 
descriptor. The indicator is 
FALSE if (and = only if) the 
specified formal is described by 
a procedure definition but the 
descriptor does not match the 
accompanying actual argument 
descriptor. 


The argument that is checked is 
given by the index, and is thus 
number 0 through 255. The format 
of the actual argument descriptor 
is identical to that of the 
procedure definition GSD record 
described in Section C.4.4.2 
above. The linker currently 
compares only the fields 
ARG SV_PASSMECH, stacking the TRUE 
indicator if they agree, FALSE if 
they do not. 
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C.5.1.2 
longword from the 


Store Group - All commands of the store 
stack upon completion of the command. 


group pop the top 
Several of 


the commands provide validation of the quantity being stored, with the 


possibility of 
next byte in the output image. 
Code Command 


20 Store Signed byte 
(TIRSC_STO_SB) 


21 Store Signed Word 
(TIR$C_STO_SW) 


22 Store Longword 
(TIRSC_STO_LW) 


23 Store Byte Displaced 
(TIRSC_STO_BD) 


24 Store Word Displaced 
(TIRSC_STO_WD) 


25 Store Longword 
Displaced 
(TIRSC_STO_LD) 


26 Store Short Literal 
(TIRSC_STO LT) 


27 Store Position- 
Independent Data 
Reference 
(TIRS$C_STO_PIDR) 


issuing truncation errors during the operation. Upon 
completion of the command, the location counter is 


pointing to the 


Description/Interpretation 


Bits 31:7 must be identical. Low 
byte written to image. 


Bits 31:15 must be identical. 
Lower word written to image. 


One longword written to image. 


Location counter subtracted from 
top of stack. Decrement value. 
Bits 31:7 must be identical. 
Byte is then written to image. 


Location counter plus 2 
subtracted from top of stack. 
Bits 31:15 must be identical. 
Word written to image. 


Location counter plus 4 
subtracted from top of stack. 
Longword written to image. 


stack, bits 
Single byte 


One longword from 
31:6 must be zero. 
written to image. 


The longword on top of stack is 
assumed to be the address of a 


data item. It occurs in a 
nonexecutable program section. 
If the address is absolute, 
command behaves as store 
longword. If address is 


relocatable, command behaves as 
store longword displaced and in 
addition provides information in 
the image header for subsequent 
linker processing. 
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Code Command 

28 Store Position- 
Independent Code 
Reference 


(TIR$C_STO_PICR) 


29 Store Repeated 
Signed Byte 
(TIRSC_STO_RSB) 


30 Store Repeated 
Signed Word 
(TIRSC_STO_ RSW) 


31 Store Repeated 


Longword (TIRS$C_STO_RL) 


32 Store Arbitrary 


Field (TIRSC_STO_ VPS) 


33 Store Unsigned Byte 
(TIRSC_STO_USB) 


Description/Interpretation 


The longword on top of the stack 
is assumed to be the address of 
an item to which a = position- 
independent instruction makes 
reference. The purpose of the 
command is to generate a 
position-independent reference. 
If the top of stack is absolute, 
the byte "9F" (hex) is written 
(which is autoincrement deferred 
addressing mode on the _ PC and 
therefore absolute) followed by 
the top as for store longword. 
If, however, top of stack is 
relocatable, the byte "EF" (hex) 
is written (which is longword 
displacement mode off PC and 
therefore relative addressing). 
Location counter is incremented. 
Then the longword is written just 
as for store longword displaced. 


This and the previous command are 
discussed further in the 
references on generation of 
position independent images. 


The longword on top of the stack 
is used as the repeat count. The 
low order .byte of next longword 
on the stack is written to the 
image the indicated number of 
times. Both longwords are 
cleaned off stack on completion. 


As above except that words are 
written. 


Analogous to above. 


The bits 0 to (s-l) of the top 
longword are written to image 
Starting at bit p of the current 
location. The command byte in 
the object module is followed by 
p and s (respectively) which are 
unsigned bytes. Only the 
specified bits of the image are 
altered. After the operation the 
location counter is the address 
of the byte containing bit (pts) 
of the location modified. Note 
that the value of pts must be 
greater than zero and less’ than 
or equal to either 32 or 
((P+8)/8)*8-1, whichever is less. 


Same as TIRSC_STO_SB except that 
bits 31:8 must be zero, 


Code 


34 


35 


36 


37 


38 


39 


40 


41 


42 


43-49 
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Command 


Store Unsigned Word 
(TIRSC_STO_USW) 


Store Repeated 
Unsigned Byte 
(TIRSC_STO_ RUB) 


Store Repeated 
Unsigned Word 
(TIRSC_STO_RUW) 


Store Byte 
(TIRSC_STO_B) 


Store Word 
(TIRSC_STO_W) 


Store Repeated Byte 
(TIRSC_STO_RB) 


Store Repeated Word 
(TIRSC_STO_RW) 


Store repeated 
Immediate Variable 
Bytes 
(TIRSC_STO_RIVB) 


Store Position 
Independent 
Reference Relative 
(TIRSC_.STO_.PIRR) 


Reserved Commands 


Description/Interpretation 


Analogous to above (Bits 31:16 


must be zero) 


Analogous to above. 


Analogous to above. 


If top longword on stack is 
is negative, then bits 31:7 must 
be 1. Otherwise, bits 31:8 must 
be zero. Low order byte is 
written to image. This command 
permits any 8 bit value from -128 
to 255 to be written to the 
image. 


If top longword is negative, bits 


31:15 must be 1. Otherwise bits 
31:16 must be zero. Low order 
word is written to image. This 


command permits any 16-bit value 
from -32768 to 65535 to be 
written to the image. 


The repeated version of store 
byte. See TIRS$C_STO_RSB_ for 
description of repeat count. 
Analogous to above. 

One byte of byte count (N) fol- 
lowed by N_ bytes. The N bytes 
are written to the image and 
repeated the number of times 
specified by the top longword of 
the stack, which is removed from 
the stack on completion. (A 0 


repeat count stores nothing.) 


The longword (longword 1) on the 
top of the stack is the address 
of a data item. If it is an 
absolute value the command is the 
same as Store Longword except 
that a second value is cleared 
from the linker stack. If the 
address is relocatable, the 
second longword (longword 2) is 
taken from the stack. If its 
value is -1l, the current value of 
the location counter is 
substituted for longword 2. The 
value then stored is longword 1 
minus longword 2). 
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C.5.1.3 Operator Group - The linker evaluates expressions in Post Fix 


Polish form. 
2's complement integers. 
string, or quadword computation. 


All arithmetic operations are performed in signed 32-bit 
There is no provision 


for floating point, 


The commands of the operator group take as operands the top one or two 


longwords on the stack. 
is the top longword on the stack. 


Upon completion of the operation, the result 
Attempts to divide by zero 


produce 


a zero result, and a nonfatal diagnostic is issued. 


Code Command 

50 No-operation 
(TIRSC_OPR_NOP) 

51 Add (TIRS$C_OPR_ADD) 

52 Subtract 
(TIRSC_OPR_SUB) 

53 Multiply 
(TIR$C_OPR_MUL) 

54 Divide 
(TIRSC_OPR_DIV) 

55 Logical AND 
(TIR$C_OPR_AND) 

56 Logical Inclusive OR 
(TIRSC_OPR_IOR) 

57 Logical Exclusive OR 
(TIRSC_OPR_EOR) 

58 Negate 
(TIR$C_OPR_NEG) 

59 Complement 
(TIRSC_OPR_COM) 

60 Insert Field 
(TIRSC_OPR_INSV) 

61 Arithmetic Shift 


(TIRSC_OPR_ASH) 


Description/Interpretation 


Top two longwords are added. 


Top 
next. 


longword is subtracted from 
Top two longwords are multiplied. 


Divisor is top longword. 


Logical AND of top two longwords. 


Inclusive OR of top two 
longwords. 

Exclusive OR of top two 
longwords. 

Top longword is negated. 

Top longword is complemented. 
This command is reserved for 
future use. It is analogous’ to 
the store of arbitrary bit field 
TIRSC_STO_VPS (code 32). The 
only difference is that the 
target for bits from top of stack 
is the next longword on the 
stack, and location counter is 
therefore unaffected. Note that 


top longword is popped and that p 
and s are bytes following command 
in the TIR record. 


The longword on top of stack is 
the shift count to apply to next 
longword. Negative quantity 
causes a right shift (with 
replication of sign bit). 
Positive causes left shift with 
zeroes moved into low order bits. 
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Code Command Description/Interpretation 

62 Unsigned Shift As above except that zeroes are 
(TIRSC_OPR_USH) moved into high and low order, 

63 Rotate Rotate count is top longword to 
(TIRSC_OPR_ROT) apply in a= rotate (left if 


positive, otherwise right) of 
next longword on_ stack. Rotate 
count must have an absolute value 
between 0 and 32. 


64 Select Remove the top longword from the 
(TIRSC_OPR SEL) stack. If it has the value TRUE 
~ (low bit set) remove and discard 
the next longword on the stack. 
If the first longword removed has 
the value FALSE (low bit clear) 
copy the next longword on the 
Stack to the one that follows. 
Thus, the command presumes there 
are three longwords on the stack. 
These are collapsed to a single 
longword which is the value of 
the second or third based on the 
value of the first. 


65 Redefine Symbol to The command has the same format 
Current Location. as the TIRSC_STA_GBL command. 
(TIRSC_OPR_REDEF) Causes the symbol to be 


re-defined on output of symbol 
table(s) to have the value of the 
location counter when this 
command is processed. The 
re-definition does not occur 
until after all image binary is 
written, If no binary is 
generated (or is aborted) the 
redefinition does not occur. 


66-79 Reserved Commands 


C.5.1.4 Control Group - The control group of commands is provided for 
manipulation of the location counter. 


Code Command Description/Interpretation 

80 Set Relocation Base The value on top of the stack is 
(TIRSC_CTL_SETRB) popped into the location counter. 

81 Augment Relocation Signed longword which is an 


Base (TIRSC_CTL_AUGRB) increment to location counter 
follows the command. 


82 Define Location The top longword on the stack is 
(TIR$C_CTL_DFLOC) removed and used as an_ index. 
The current location counter is 
stored away, qualified by the 
index and the object module 
containing it. This command is 
only legal in traceback and debug 
records. 
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Code Command Description/Interpretation 
83 Set Location The top longword on the’ stack is 
(TIRSC_CTL_STLOC) removed and used as an index. 


The saved location counter (from 
a corresponding TIRSC_CTL_DFLOC) 
is set as the current location 
counter, and the location counter 
saved for index (n) is deleted. 
This command is only legal in 
traceback and debug records. 


84-127 Reserved Commands 


C.5.2 Record Length 


TIR records may be quite long. There is an implementation limit 
defined by OBJSC_MAXRECSIZ. The maximum record size of the module is 
recorded in the header word. 


C.5.3 Side Effects and Optimization 


In the interest of performance of the linker a few implementation 
decisions and their possible side effects should be noted. 


1. For all store repeated commands, if the quantity being stored 
is zero, the linker does not write the zeroes into the bytes. 
The reason for this is that the pages of an image are 
guaranteed to be zero unless’ otherwise initialized by the 
compiler. To achieve this, demand zero pages are used within 
the linker and were the linker to attempt to write zeroes, the 
fact that these are still empty pages of the image is lost. 
Thus, it becomes very difficult to compress from the image all 
empty pages. 


There is, however, a Side effect to this behavior, in that if 
a cell of an image has been previously initialized, it will 
not be zeroed by any repeated store commands. This can occur 
in multiple modules contributing to and attempting to 
initialize the content of overlaid program sections. Notice, 
however, that the results of such multiple initialization are 
then dependent on the order of processing of object modules. 
This side effect is therefore considered to be acceptable. 


2. The linker is a two-pass processor of object modules. The 
content of TIR records is completely ignored on the first pass 
but verified and acted upon on the second pass. However, if 
no image is being produced because of a command or link time 
error, all TIR records (as well as DBG and TBT records) are 
ignored. A side effect, considered quite acceptable, is that 
errors (user or compiler) potentially detectable on pass_ two 
will not be detected. Truncation errors are the most likely 
example of such undetected situations. 
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C.6 END OF MODULE (EOM) RECORD (OBJ$C_EOM) 


This record declares the end of a module. It declares the severity of 
errors encountered by language processor, and, optionally, it declares 
a transfer address within a program section in this module. The 
format is as follows: 















RECORD TYPE 3 1 byte 
ERROR SEVERITY 1 byte 
P-SECT INDEX 1 byte 
TRANSFER 4 bytes 
ADDRESS 

TRANSFER FLAGS — 1 byte 





This record will be 2, 7, or 8 bytes, depending on the existence of a 
transfer address. Note that the program section specification is by 
its index within the module, as used above. The transfer address is 
an offset from the base of this module's contribution to the specified 
program section. The transfer flags byte may only be present if the 
transfer address is present. 


C.6.1 Error Severity 


The error severity byte specifies to the linker whether errors were 
encountered in the source code. It also indicates the severity of any 
errors encountered. 


Value Interpretation by linker 
0 No errors 
1 Warnings were generated by language processor. Proceed 


with link but issue warning message. 


2 Errors were severe, proceed with link, but do not 
produce an executable image. 


3 Abort the link. 
4-10 Reserved. 
11-255 Ignored. 


C.6.2 Transfer Address Flags 


The transfer address flags byte directs the linker in the processing 
of transfer addresses. 


Bit Interpretation by linker 


0 Weak transfer address. If a transfer address 
is already defined, no error is produced. 


1:7 Reserved, must be 0, 
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C.7 DEBUGGER INFORMATION (DBG) RECORDS (OBJS$C_DBG) 


The purpose of debugger information records is to allow the language 
processors to pass information, such as descriptions of local 
variables, of the compilation to the debugger. The transmission of 
this information may make use of all the functions (commands) 
available in the TIR set. 


The command stream in DGB records generates what is referred to as the 
debug symbol table (DST). The DST follows immediately the binary of 
the user image and the image header contains a descriptor of where in 
the file such data has been written. The production of the DST in 
Memory makes use of a separate location counter within the linker. 
This location counter is initialized as if the DST were the highest 
addressed part of the program region of the image. Note, however, the 
DST is not in fact mapped into the user image. 


The linker produces a DST only if the debugging qualifier was 
specified at link time and only if an executable image is being 
produced. If either of these is not true, DBG records are ignored. 
See the above discussion of the side effects in TIR record processing. 


C.7.1 Traceback Information (TBT) Records (OBJ$C_TBT) 


Traceback information records are the means by which language 
processors pass information to the facility which produces a traceback 
of the call stack. From the point of view of the linker and its 
processing of these records, they are identical to DBG records, That 
is, they may be mixed with DBG records and all data generated goes 
into the DST as if they were in fact DBG records. 


The purpose of separating this information from that contained in DBG 
records is to allow inclusion of a DST containing only traceback data 
when no debugging is requested at link time. If the production of 
traceback information is disabled at link time then these records are 
ignored. See the above section on side effects in processing TIR 
records. 


C.8 LINK OPTION SPECIFICATION (LNK) RECORDS (OBJ$C_LNK) 


The link option specification records are defined for the purpose of 
allowing the compiler to provide the linker with default parameters 
that are used if none were given by the user at link time. Options of 
interest are libraries to be searched to resolve undefined symbols, 
modules to be included in the link, adjustment of stack and buffer 
region sizes. 


The exact set of commands allowable will be supplied later, along with 
the interaction of conflicting object module LNK records and user 
commands. The general philosophy is to use the most recently 
specified parameters unless’ there are good reasons to the contrary. 
These records are currently ignored by the linker. 
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THE ANALYZE PROGRAM 


The object module analysis (ANALYZE) program checks an object modulé 
to see if it is in the correct format for input to the VAX-11 Linker. 
(The program can also analyze a concatenated file containing several 
object modules.) This program is a diagnostic tool for writers of 
compilers or assemblers that must generate native-mode code. To use 
this program intelligently, you must be familiar with the VAX-1ll 

object language specification in Appendix C. 


To invoke the program, use the DCL command ANALYZE. The program can 
analyze the entire module or only specified types of records. It 
checks the record type, contents, and sequence of each object module 
record it examines. The program creates an output file containing a 
record=by-~record analysis of the object module, including 
identification of any errors in the module. 


The program, however, haS a more limited set of operations than the 
linker. The ANALYZE program: 


e Does not verify that all data arguments to commands are in the 
correct format 


e Does not check whether "store data" commands are_ storing 
within legal address limits 


These restrictions exist because the program does not actually perform 
the object language commands in the module. Therefore, if you have 
run ANALYZE against an object module and received no errors, you 
should perform the additional check of linking the module, requesting 
a full map. 


D.1 THE ANALYZE COMMAND 


The ANALYZE command requires no user privileges and follows’ the 
standard DCL syntax conventions. For a complete discussion of this 
command, see the VAX/VMS Command Language User's Guide. The general 
format of the command is as follows: 


SANALYZE input-file-spec[/MHD] [/GSD] [/TIR] [/DBG] [/TBT] [/EOM] 
Command Qualifiers: Default: 


/OUTPUT=file-spec Output file name = input file name; 
output file type = ANL 


/ INTERACTIVE /NOINTERACTIVE -- you are not prompted 
after each record is displayed. 
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D.2 THE OUTPUT FILE 


The analysis of each record contains information pertinent to that 
record type, and begins with a line in the following format: 


>>>>>RECORD [number] IS [record type} [number of] BYTES LONG 


For example: 
>>>>>RECORD 4 IS A TEXT/RELOCATION 58 BYTES LONG 


Errors in the object module are identified in lines beginning with 
asterisks. For example: 


****%* RECORD 3 IS RESERVED TYPE 49 ##RARHRARHRRERRAER 


The program also prints the hexadecimal representation of the 
erroneous record's contents. A complete list of the error messages 
appears later in this appendix. 


The following subsections (D.2.1 to D.2.7) discuss the information 
given for the following record types: 


Debugger information record 

End of module record 

Global symbol directory (GSD) record 

Module header record 

Subheader record 

Text information and relocation (TEXT/RELOCATION) record 
Traceback information record 


The record types are explained in alphabetical order for ease of 
reference. In the actual output file, the order reflects the order of 
the records in the module. The only requirement for sequence is” that 
a module header and any subheader records come first, and an end of 
module record come last. 


D.2.1 Debugger Information Record 


Debugger information records identify one or more commands to the 
linker, including the data or symbol associated with each command. 
(The object language commands are discussed in Appendix C.) For 
example, a Store Immediate (STOIM) command is followed by the decimal 
number of bytes to be stored and the hexadecimal representation of 
this data. A Stack Global (STA GBL) command is followed by the name 
of the symbol whose value is to bé placed on the linker stack. 


To the right of each command is the notation "STACK =n," where "n" is 
the decimal number of bytes that would be on the linker's internal 
stack if the linker were actually processing the object module. The 
ANALYZE program reports an error if the count is not equal to zero at 
the end of each object module analysis (that is, if bytes would be 
left on the linker stack or if more bytes would be removed than were 
placed on the stack). 
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D.2.2 End of Module Record 
The end of module record contains the following information: 
@e Number of compiler errors and warnings, including any _ link 
abort specification by the language processor due to fatal 
compilation errors 


e Number of the program section that contains the transfer 
address 


e Transfer address expressed as an offset from the program 
section base 


e Number of program sections defined in the module 


D.2.3 Global Symbol Directory (GSD) Record 


A GSD record can contain one or more program section definitions, one 
or more global symbol specifications, or a combination or both. 


For each program section definition, the following information is 
given: 


e Program section alignment 
e Flag bits that are set 
@e Maximum length of the program section 


For each global symbol specification, the following information is 
given: 


e Specification function - that is, whether the specification is 
a reference to a global symbol or a definition of a global 
symbol 


e Data type (For example: "procedure entry mask," data type 23; 
or “unknown," data type 0) 


e Flag bits that are set 


e Number of the program section in which the symbol is defined 
(for global symbol definitions only) 


@ Value of the symbol (for global symbol definitions only) 


e Name of the global symbol 


D.2.4 Module Header Record 


The module header record lists the following information about’ the 
modules 


e Structure level of the object language 
@ Maximum length that a record in the module can have 


e@ Name 
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e Identification 
e Creation date and time 


e Date and time of the last patch 


D.2.5 Subheader Records 
Most module subheader records consist of ASCII data and are printed as 
such. These subheader types include identification of the language 
processor used, the compilation options specified, and the title 
specified for the compilation listing. 
Another type of subheader identifies the maintenance status if the 
module has been patched. The maintenance status subheader record 
lists the following information: 

e Patch utility name and version number 

e UIC under which the patch was executed 

e Input file specification for the patch 

e Correction file specification for the patch 


e Date and time of the patch 


e Sequential patch number 


D.2.6 Text Information and Relocation (TEXT/RELOCATION) Record 


Text information and relocation records contain the same type of 
information as debugger information records (see Section D.2.1). 


D.2.7 Traceback Information Records 


Traceback information records contain the same type of information as 
debugger information records (see Section D.2.1). 


D.3 ANALYZE PROGRAM ERROR MESSAGES 

Errors in the object module are identified by lines beginning with 
asterisks (*****), Most of these error messages appear in the output 
file, but some are displayed on the terminal. The messages are 
presented in alphabetical order, with explanations for those that are 
not self-explanatory. 

ABSOLUTE PSECT HAS NON-ZERO LENGTH 

All absolute program sections must have a length of zero. 


ARGUMENT DESCRIPTOR MISSING FOR FORMAL ARGUMENT #{[number ] 


The specified argument requires a character string descriptor. 
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ARGUMENT INDEX IS MISSING 
BYTE COUNT GOES BEYOND END OF RECORD [number of] BYTES 


A byte count contained in the record indicates that the data that 
follows does not fit within the record. 


[number of] BYTES WERE LEFT ON THE LINKER'S STACK 
The object language commands in the module place more bytes on 
the linker's internal stack than they remove. The linker's stack 


should be empty when it finishes processing each object module. 


{number of] BYTES WERE NOT PLACED ON THE LINKER'S STACK BUT WERE 
REMOVED FROM IT 


The object language commands in the module remove more bytes from 
the linker's stack than they place on it. 


COMMAND [number] IS ILLEGAL TYPE [number] 
COMMAND [number] IS RESERVED [code] 

(See Appendix C for a list of the assigned and reserved codes.) 
CORRECTION FILE SPECIFICATION WAS NOT IN COMPRESSED FORM 


The correction file specification in the maintenance’ status 
subheader record contains nulls, tabs, or blanks. 


DATE/TIME FIELD CONTAINS ILLEGAL CHARACTER CHARACTER [position] 
IS [ASCII representation] ([number] HEX) 


ENTRY POINT GSD HAS ILLEGAL LENGTH {number of] BYTES - NOT BETWEEN 
{minimum number] AND [maximum number] 


FILE [file name] DOES NOT END WITH EOM 
The end of the module record is missing or out of sequence. 
FIRST CHARACTER OF GLOBAL SYMBOL IS NUMERIC OR BLANK 
FIRST CHARACTER OF CORRECTION FILE SPECIFICATION IS NUMERIC OR BLANK 
| FIRST CHARACTER OF INPUT FILE SPECIFICATION IN NUMERIC OR BLANK 
FIRST CHARACTER OF MODULE NAME IS NUMERIC OR BLANK 
FIRST CHARACTER OF PATCH UTILITY NAME IS NUMERIC OR BLANK 
FIRST CHARACTER OF P-SECT NAME IS NUMERIC OR BLANK 
FORMAL ARGUMENT DESCRIPTOR IS MISSING REMAINING BYTE COUNT 
The record is not long enough to hold the remaining byte count. 


GLOBAL SYMBOL CONTAINS ILLEGAL CHARACTERS CHARACTER [position] Is 
[ASCII representation] ({number] HEX) 


Valid characters are . (period), $ (dollar sign), _(underscore), 
0 through 9, and A through Z. 
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GLOBAL SYMBOL DEFINITION RECORD HAS ILLEGAL LENGTH {number of] 
BYTES - NOT BETWEEN [minimum length] AND [maximum length] 


GLOBAL SYMBOL FIELD LENGTH [length] ILLEGAL NOT 1 TO [number of] 
CHARACTERS 


GLOBAL SYMBOL LENGTH ( [number of] BYTES ) ILLEGAL - SHOULD BE 1 TO 
{number of] CHARACTERS 


GLOBAL SYMBOL REFERENCE RECORD HAS ILLEGAL LENGTH (number of] 
BYTES — NOT BETWEEN [minimum number] AND [maximum number] 


GSD TYPE [number] DOES NOT EXIST 
(Appendix C lists the valid GSD types.) 


IDENT CONTAINS ILLEGAL CHARACTER CHARACTER [position] Is {ASCII 
representation] ([number] HEX) 


IDENT LENGTH [length] ILLEGAL SHOULD BE 1 TO [number of] CHARACTERS 
ILLEGAL ALIGNMENT - GREATER THAN [maximum permitted] 


ILLEGAL CORRECTION FILE SPECIFICATION LENGTH OF ZERO, SHOULD BE 1 TO 
[number of] CHARACTERS 


The correction file specification in the maintenance’ status 
subheader record is zero. 


ILLEGAL INPUT FILE SPECIFICATION LENGTH OF ZERO, SHOULD BE 1 TO 
{number of] CHARACTERS 


The input file specification in the maintenance status subheader 
record has a length of zero. 


ILLEGAL MAXIMUM RECORD LENGTH - MUST BE BETWEEN [minimum length] AND 
[maximum length] 


The maximum record length for the module, as specified in the 
module header record, is outside the acceptable range. 


ILLEGAL PSECT ALLOCATION - EXCEEDS [number of] BYTES 


ILLEGAL RECORD LENGTH [length] NOT BETWEEN [minimum number] AND 
{maximum number] BYTES 


ILLEGAL SEVERITY CODE [code] 


The severity code specified in an end of module record is illegal 
(see Section C.6.1). 


ILLEGAL STARTING BIT POSITION- NOT 0 TO 31 


A variable bit field command specifies an illegal starting bit 
position. 


ILLEGAL STRUCTURE LEVEL ~- ONLY [highest level currently supported] IS 
SUPPORTED 


The structure level (format) of the object language in the module 
is not yet supported by the ANALYZE program. The program 
analyzes only structure levels 0 through the level specified in 
the message. 


THE ANALYZE PROGRAM 


ILLEGAL SUBHEADER TYPE OF [type] 


The specified subheader type is not recognized by the ANALYZE 
program. 


ILLEGAL SYNTAX FOR DATE/TIME 


The date and time must be in a fixed-length ASCII string with the 
following format: 


dd-mon-yy hh:mm:ss 


ILLEGAL TRANSFER ADDRESS (NOT BETWEEN 0 AND [highest available virtual 
address] ) 


The transfer address is outside the virtual address space. 

[flag bit number] ILLEGALLY 
The specified flag bit is set, but is reserved (invalid). This 
message follows the message "THE FOLLOWING FLAG BITS ARE SET:" 
and a listing of the flag bits legally set. 


INCOMPLETE RECORD - NEXT FIELD AT BYTE [location within record] BEYOND 
RECORD 


A byte count contained in a module header record is greater than 
the number of bytes remaining in the record. 


INPUT FILE SPECIFICATION WAS NOT IN COMPRESSED FORM 


The input file specification of the maintenance status subheader 
record contains blanks, nulls, or tabs. 


INVALID ARGUMENT INDEX OF [number] NOT BETWEEN [minimum] AND [maximum] 


INVALID MAXIMUM ACTUAL ARGUMENT COUNT OF [number] NOT BETWEEN [number] 
AND [number] 


INVALID MINIMUM ACTUAL ARGUMENT COUNT OF [number] NOT BETWEEN [number] 
AND [number] 


INVALID SEQUENCE - MHD SHOULD NOT FOLLOW TYPE [type] RECORD 
The only record type that can precede a module header is type 3 
(end of module record for the previous module in a concatenated 
file). 

INVALID SEQUENCE - SHOULD NOT FOLLOW EOM OR BEGIN A MODULE 


Nothing can follow an end of module record except an end-of-file 
or a module header record in a concatenated file. 


INVALID SEQUENCE - SUB-HEADER RECORD SHOULD NOT FOLLOW TYPE [type] 
RECORD 


A subheader record should only follow a module header record or 
another subheader record. 


INVALID SYNTAX OF CORRECTION FILE SPECIFICATION IN: [error part] 


The correction file specification in the maintenance status 
subheader record has a syntax error in the specified part. 
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LANGUAGE PROCESSOR RECORD FOLLOWS [number of] TIR, GSD, OR TBT RECORDS 


The language processor subheader record should follow the module 
header record. 


LANGUAGE PROCESSOR RECORD LARGER THAN [number of] CHARACTERS 
MINIMUM IS GREATER THAN MAXIMUM 


The minimum actual argument count specified is greater than the 
maximum actual argument count specified. 


MODULE NAME CONTAINS ILLEGAL CHARACTERS CHARACTER [position] IS [ASCII 
representation] ([number] HEX) 


MODULE NAME LENGTH ILLEGAL SHOULD BE 1 TO [number of] CHARACTERS 
NO P-SECTIONS DEFINED IN MODULE 
An object module must contain at least one program section. 


PATCH UTILITY NAME CONTAINS ILLEGAL CHARACTER CHARACTER [position] Is 
[ASCII representation] ([number] HEX) 


The patch utility name in the maintenance status subheader record 
contains the specified illegal character. 


PATCH UTILITY NAME LENGTH ILLEGAL SHOULD BE 1 TO [number of] 
CHARACTERS 


The length of the patch utility name in the maintenance’ status 
subheader record is illegal. 


PATCH UTILITY VERSION CONTAINS ILLEGAL CHARACTERS 


The patch utility version in the maintenance status subheader 
record contains an illegal character. 


PATCH UTILITY VERSION LENGTH [length] ILLEGAL SHOULD BE 1 TO _ [number 
of] CHARACTERS 


The length of the patch utility version in the maintenance status 
subheader record is outside the indicated range. 


PROCEDURE WITH FORMAL ARGUMENT DEFINITION HAS ILLEGAL LENGTH ( [number 
of] BYTES ) - NOT BETWEEN [minimum number] AND [maximum number] 


PROCEDURE WITH FORMAL ARGUMENT DEFINITION IS MISSING MAXIMUM ACTUAL 
ARGUMENT COUNT 


PROCEDURE WITH FORMAL ARGUMENT DEFINITION IS MISSING MINIMUM ACTUAL 
ARGUMENT COUNT 


P-SECT DEFINITION RECORD HAS ILLEGAL LENGTH [number of] BYTES - NOT 
BETWEEN [minimum length] AND [maximum length] 


P-SECT NAME CONTAINS ILLEGAL CHARACTER CHARACTER [position] IS {ASCII 
representation] ([number] HEX) 


PSECT NAME LENGTH IS ILLEGAL [length] 
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P-SECTION NUMBER EXCEEDS COUNT OF THOSE DEFINED IN MODULE (number of 
program sections defined] 


The program section number supplied in the program section index 
field of an end of module record is greater than the number 
assigned to any program section in the module. In other words, 
the transfer address is specified as being in a nonexistent 
program section. 


[number of] PSECT(S) DEFINED - TIR REFERENCES PSECT NUMBER (number } 


A text information and relocation record contains a reference to 
a program section that is not defined in the module. Program 
sections are assigned a number in the range 0 through 255, in the 
order in which they are defined. 


RECORD [number] IS ILLEGAL - ZERO LENGTH 

The record length byte in the specified record contains zero. 
RECORD [{number] IS RESERVED TYPE [type] 

The record type of the specified record in invalid. 


RECORD [number] LENGTH ([length]) GREATER THAN MAX. PERMITTED LENGTH 
({[maximum length]) 


The length of the specified record is greater than the maximum 
permitted length specified in the module header record. The last 
number in the message is the actual length of the specified 
record. 


REQUIRED DATA NOT CONTAINED WITHIN RECORD 
Inconsistencies exist within the record that make it impossible 
for the ANALYZE program to interpret it. For example, a byte 
count of 3 might be followed by a symbol with more than 3 
characters. 


This message is followed by the contents of the record in 
hexadecimal representation. 


RESERVED BIT #{number] SET IN ARGUMENT VALIDATION CONTROL BYTE 
RESERVED DATA TYPE 


(For a list of legal data types, see the "Procedure Calling and 
Condition Handling" appendix in the VAX-1]1 Architecture Handbook 
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